Add Support for GetParam for Stat Sizes (#5111)

Author: nibanks

docs/Settings.md

@@ -118,6 +118,7 @@ These parameters are accessed by calling [GetParam](./api/GetParam.md) or [SetPa
 | `QUIC_PARAM_GLOBAL_EXECUTION_CONFIG`<br> 9 (preview)        | QUIC_GLOBAL_EXECUTION_CONFIG   | Both      | Globally configure the execution model used for QUIC. Must be set before opening registration.        |
 | `QUIC_PARAM_GLOBAL_TLS_PROVIDER`<br> 10           | QUIC_TLS_PROVIDER       | Get-Only  | The TLS provider being used by MsQuic for the TLS handshake.                                          |
 | `QUIC_PARAM_GLOBAL_STATELESS_RESET_KEY`<br> 11    | uint8_t[]               | Set-Only  | Globally change the stateless reset key for all subsequent connections.                               |
+| `QUIC_PARAM_GLOBAL_STATISTICS_V2_SIZES`<br> 12    | uint32_t[]               | Get-only  | Array of well-known sizes for each version of the QUIC_STATISTICS_V2 struct. The output array length is variable; pass a buffer of uint32_t and check BufferLength for the number of sizes returned. See GetParam documentation for usage details. |
 | `QUIC_PARAM_GLOBAL_VERSION_NEGOTIATION_ENABLED`<br> (preview) | uint8_t (BOOLEAN) | Both | Globally enable the version negotiation extension for all client and server connections. |
 
 ## Registration Parameters

docs/api/GetParam.md

@@ -71,6 +71,38 @@ Sample of double-call:
     }
 ```
 
+# Special Parameters
+
+## QUIC_PARAM_GLOBAL_STATISTICS_V2_SIZES
+
+Returns an array of well-known sizes (in bytes) for each version of the `QUIC_STATISTICS_V2` struct. This allows applications to determine the correct buffer size for statistics queries, even as new versions are added in future MsQuic releases.
+
+> **Note** - Most applications should **not** leverage this and instead directly call to query the `QUIC_STATISTICS_V2`. This API is only necessary for layers on top of MsQuic that need to pass through this information to additional layers on top of them.
+
+- **Type:** `uint32_t[]` (array of struct sizes)
+- **Get-only**
+- **Variable-length:** The number of sizes returned may change in future versions. The caller should pass a buffer of `uint32_t` and use the double-call pattern to determine the required buffer size.
+
+**Sample usage:**
+```c
+uint32_t Sizes[8]; // Large enough for future growth
+uint32_t BufferLength = sizeof(Sizes);
+QUIC_STATUS Status =
+    MsQuic->GetParam(
+        NULL,
+        QUIC_PARAM_GLOBAL_STATISTICS_V2_SIZES,
+        &BufferLength,
+        Sizes);
+if (Status == QUIC_STATUS_BUFFER_TOO_SMALL) {
+    // BufferLength is set to required size (in bytes)
+    // Allocate a larger buffer and call again
+}
+uint32_t NumSizes = BufferLength / sizeof(uint32_t);
+// Sizes[0..NumSizes-1] now contains the struct sizes for each version
+```
+
+See also: [Settings.md](../Settings.md#global-parameters)
+
 # See Also
 
 [Settings](../Settings.md#api-object-parameters)<br>

src/core/library.c

@@ -1498,6 +1498,32 @@ QuicLibraryGetGlobalParam(
         Status = QUIC_STATUS_SUCCESS;
         break;
 
+    case QUIC_PARAM_GLOBAL_STATISTICS_V2_SIZES: {
+        static const uint32_t StatSizes[] = {
+            QUIC_STATISTICS_V2_SIZE_1,
+            QUIC_STATISTICS_V2_SIZE_2,
+            QUIC_STATISTICS_V2_SIZE_3,
+            QUIC_STATISTICS_V2_SIZE_4
+        };
+        static const uint32_t NumStatSizes = ARRAYSIZE(StatSizes);
+        uint32_t MaxSizes = *BufferLength / sizeof(uint32_t);
+        if (MaxSizes == 0) {
+            *BufferLength = NumStatSizes * sizeof(uint32_t); // Indicate the max size.
+            Status = QUIC_STATUS_BUFFER_TOO_SMALL;
+            break;
+        }
+        if (Buffer == NULL) {
+            Status = QUIC_STATUS_INVALID_PARAMETER;
+            break;
+        }
+        const uint32_t ToCopy =
+            CXPLAT_MIN(MaxSizes, NumStatSizes) * sizeof(uint32_t);
+        CxPlatCopyMemory(Buffer, StatSizes, ToCopy);
+        *BufferLength = ToCopy;
+        Status = QUIC_STATUS_SUCCESS;
+        break;
+    }
+
     default:
         Status = QUIC_STATUS_INVALID_PARAMETER;
         break;

src/cs/lib/msquic_generated.cs

@@ -3612,6 +3612,9 @@ internal static unsafe partial class MsQuic
         [NativeTypeName("#define QUIC_PARAM_GLOBAL_STATELESS_RESET_KEY 0x0100000B")]
         internal const uint QUIC_PARAM_GLOBAL_STATELESS_RESET_KEY = 0x0100000B;
 
+        [NativeTypeName("#define QUIC_PARAM_GLOBAL_STATISTICS_V2_SIZES 0x0100000C")]
+        internal const uint QUIC_PARAM_GLOBAL_STATISTICS_V2_SIZES = 0x0100000C;
+
         [NativeTypeName("#define QUIC_PARAM_CONFIGURATION_SETTINGS 0x03000000")]
         internal const uint QUIC_PARAM_CONFIGURATION_SETTINGS = 0x03000000;
 

src/inc/msquic.h

@@ -946,6 +946,7 @@ void
 #endif
 #define QUIC_PARAM_GLOBAL_TLS_PROVIDER                  0x0100000A  // QUIC_TLS_PROVIDER
 #define QUIC_PARAM_GLOBAL_STATELESS_RESET_KEY           0x0100000B  // uint8_t[] - Array size is QUIC_STATELESS_RESET_KEY_LENGTH
+#define QUIC_PARAM_GLOBAL_STATISTICS_V2_SIZES           0x0100000C  // uint32_t[] - Array of sizes for each QUIC_STATISTICS_V2 version. Get-only. Pass a buffer of uint32_t, output count is variable. See documentation for details.
 
 //
 // Parameters for Registration.

src/rs/ffi/linux_bindings.rs

@@ -174,6 +174,7 @@ pub const QUIC_PARAM_GLOBAL_LIBRARY_GIT_HASH: u32 = 16777224;
 pub const QUIC_PARAM_GLOBAL_EXECUTION_CONFIG: u32 = 16777225;
 pub const QUIC_PARAM_GLOBAL_TLS_PROVIDER: u32 = 16777226;
 pub const QUIC_PARAM_GLOBAL_STATELESS_RESET_KEY: u32 = 16777227;
+pub const QUIC_PARAM_GLOBAL_STATISTICS_V2_SIZES: u32 = 16777228;
 pub const QUIC_PARAM_CONFIGURATION_SETTINGS: u32 = 50331648;
 pub const QUIC_PARAM_CONFIGURATION_TICKET_KEYS: u32 = 50331649;
 pub const QUIC_PARAM_CONFIGURATION_VERSION_SETTINGS: u32 = 50331650;

src/rs/ffi/win_bindings.rs

@@ -168,6 +168,7 @@ pub const QUIC_PARAM_GLOBAL_LIBRARY_GIT_HASH: u32 = 16777224;
 pub const QUIC_PARAM_GLOBAL_EXECUTION_CONFIG: u32 = 16777225;
 pub const QUIC_PARAM_GLOBAL_TLS_PROVIDER: u32 = 16777226;
 pub const QUIC_PARAM_GLOBAL_STATELESS_RESET_KEY: u32 = 16777227;
+pub const QUIC_PARAM_GLOBAL_STATISTICS_V2_SIZES: u32 = 16777228;
 pub const QUIC_PARAM_CONFIGURATION_SETTINGS: u32 = 50331648;
 pub const QUIC_PARAM_CONFIGURATION_TICKET_KEYS: u32 = 50331649;
 pub const QUIC_PARAM_CONFIGURATION_VERSION_SETTINGS: u32 = 50331650;

src/test/lib/ApiTest.cpp

@@ -2787,6 +2787,102 @@ void QuicTestGlobalParam()
                 nullptr));
     }
 
+    //
+    // QUIC_PARAM_GLOBAL_STATISTICS_V2_SIZES
+    //
+    {
+        TestScopeLogger LogScope0("QUIC_PARAM_GLOBAL_STATISTICS_V2_SIZES");
+        const uint32_t Expected[] = {
+            QUIC_STATISTICS_V2_SIZE_1,
+            QUIC_STATISTICS_V2_SIZE_2,
+            QUIC_STATISTICS_V2_SIZE_3,
+            QUIC_STATISTICS_V2_SIZE_4
+        };
+
+        //
+        // Expect buffer too small
+        //
+        uint32_t Length = 0;
+        TEST_QUIC_STATUS(
+            QUIC_STATUS_BUFFER_TOO_SMALL,
+            MsQuic->GetParam(
+                nullptr,
+                QUIC_PARAM_GLOBAL_STATISTICS_V2_SIZES,
+                &Length,
+                nullptr));
+        TEST_TRUE(Length >= sizeof(Expected));
+
+        //
+        // NULL pointer output error case
+        //
+        Length = sizeof(uint32_t);
+        TEST_QUIC_STATUS(
+            QUIC_STATUS_INVALID_PARAMETER,
+            MsQuic->GetParam(
+                nullptr,
+                QUIC_PARAM_GLOBAL_STATISTICS_V2_SIZES,
+                &Length,
+                nullptr));
+
+        //
+        // Retrieve the sizes
+        //
+        uint32_t Sizes[8] = {0};
+        Length = sizeof(Sizes);
+        TEST_QUIC_SUCCEEDED(
+            MsQuic->GetParam(
+                nullptr,
+                QUIC_PARAM_GLOBAL_STATISTICS_V2_SIZES,
+                &Length,
+                Sizes));
+        TEST_TRUE(Length % sizeof(uint32_t) == 0);
+        TEST_TRUE(Length >= sizeof(Expected));
+        for (uint32_t i = 0; i < ARRAYSIZE(Expected); ++i) {
+            TEST_EQUAL(Sizes[i], Expected[i]);
+        }
+
+        //
+        // Partial retrieve
+        //
+        uint32_t SingleSize = 0;
+        Length = sizeof(SingleSize);
+        TEST_QUIC_SUCCEEDED(
+            MsQuic->GetParam(
+                nullptr,
+                QUIC_PARAM_GLOBAL_STATISTICS_V2_SIZES,
+                &Length,
+                &SingleSize));
+        TEST_EQUAL(Length, sizeof(uint32_t));
+        TEST_EQUAL(SingleSize, QUIC_STATISTICS_V2_SIZE_1);
+
+        //
+        // Non-multiple of sizeof(uin32_t)
+        //
+        Length = sizeof(uint32_t) + 1;
+        TEST_QUIC_SUCCEEDED(
+            MsQuic->GetParam(
+                nullptr,
+                QUIC_PARAM_GLOBAL_STATISTICS_V2_SIZES,
+                &Length,
+                Sizes));
+        TEST_EQUAL(Length, sizeof(uint32_t));
+        TEST_EQUAL(Sizes[0], QUIC_STATISTICS_V2_SIZE_1);
+
+        //
+        // Too Small Receive
+        //
+        uint8_t SmallSingleSize = 0;
+        Length = sizeof(SmallSingleSize);
+        TEST_QUIC_STATUS(
+            QUIC_STATUS_BUFFER_TOO_SMALL,
+            MsQuic->GetParam(
+                nullptr,
+                QUIC_PARAM_GLOBAL_STATISTICS_V2_SIZES,
+                &Length,
+                &SmallSingleSize));
+        TEST_TRUE(Length >= sizeof(Expected));
+    }
+
     QuicTestStatefulGlobalSetParam();
 }