PCW_REGISTRATION_INFORMATION結構 (wdm.h)

發行項
03/01/2024

PCW_REGISTRATION_INFORMATION 結構提供提供者和計數器集的詳細數據。大部分開發人員都會使用 CTRPP 產生的 RegisterXxx 或 InitRegistrationInformationXxx 函式，而不是直接使用此結構。

語法

typedef struct _PCW_REGISTRATION_INFORMATION {
  ULONG                   Version;
  PCUNICODE_STRING        Name;
  ULONG                   CounterCount;
  PPCW_COUNTER_DESCRIPTOR Counters;
  PPCW_CALLBACK           Callback;
  PVOID                   CallbackContext;
  PCW_REGISTRATION_FLAGS  Flags;
} PCW_REGISTRATION_INFORMATION, *PPCW_REGISTRATION_INFORMATION;

成員

Version

數值，指定提供者所需的 Windows (PCW 性能計數器版本) 。

在 10.0.19645 () NTDDI_VERSION < NTDDI_VERSION_MN 之前的 Windows 上執行時， Version 字段必須設定為 PCW_VERSION_1 (0x100) 。在 Windows 10.0.19645 和更新版本 () NTDDI_VERSION >= NTDDI_VERSION_MN 上執行時，這可能設定為 PCW_VERSION_1 (0x100) 或 PCW_VERSION_2 (0x200) 。 Version如果欄位設定為無法辨識的值，PcwRegister則會傳回STATUS_INVALID_PARAMETER_2。

使用 CTRPP 產生的 RegisterXxx 或 InitRegistrationInformationXxx 函式時， Version 字段會設定為 PCW_CURRENT_VERSION，這相當於下列其中一個值，視的編譯時間值 NTDDI_VERSION而定：

條件	PCW_CURRENT_VERSION值
`NTDDI_VERSION < NTDDI_WIN10_FE`	PCW_VERSION_1 (0x0100)
`NTDDI_VERSION >= NTDDI_WIN10_FE`	PCW_VERSION_2 (0x0200)

如果您的程式代碼是以建置，NTDDI_VERSION >= NTDDI_WIN10_FE但需要在舊版 Windows 上執行，則必須如 PcwRegister 檔中所述進行設定Version = PCW_VERSION_1。

Name

字串的指標，其中包含要註冊之計數器集的名稱。此字串不得為NULL或空白。

請注意，計數器集名稱比較不區分大小寫。如果在兩個計數器集註冊中使用相同的計數器集名稱，取用者會從這兩個註冊收集數據。

CounterCount

參數中 Counters 提供的描述項數目。

Counters

這個計數器集計數器的描述項陣列。從呼叫或 PcwAddInstance所提供的PcwCreateInstance數據區塊擷取計數器值時，將會使用描述元中的資訊。

Callback

選擇性 PCW_CALLBACK 回呼函式的指標，通知提供者與這個計數器集相關的事件。如果不需要回呼 (，此字段可能是 NULL，亦即，如果計數器集實例會透過 PcwCreateInstance 和 PcwCloseInstance) 來管理。

CallbackContext

每次叫用時，都會傳遞至提供者定義 PCW_CALLBACK 回呼函式的指標值。

Flags

Flags只有在時NTDDI_VERSION >= NTDDI_WIN10_MN，才能使用欄位。

Flags如果Version欄位小於 PCW_VERSION_2，則會忽略欄位。

欄位 Flags 會啟用的特殊行為 PcwRegister。設定為一或多個 PCW_REGISTRATION_FLAGS 值的組合：

PCW_REGISTRATION_FLAGS	意義
PcwRegistrationNone (0x0)	默認 (不需要任何特殊行為) 。
PcwRegistrationSiloNeutral (0x1)	表示所有伺服器尋址接收器中的取用者都應該看到此註冊。根據預設，只有在建立註冊時作用中的伺服器尋址接收器取用者才會看到註冊 (，也就是呼叫) 時 `PcwRegister` 附加至線程的註冊。

備註

PcwRegister 函式會採用Info參數，這個參數是這個結構的指標。

CTRPP 產生的 InitRegistrationInformationXxx 函式

大部分開發人員不需要直接使用 PCW_REGISTRATION_INFORMATION 。相反地，他們會使用 CTRPP 工具編譯指令清單，並使用 CTRPP 產生的標頭中的 RegisterXxx 或 InitRegistrationInformationXxx 函式。產生的 Register 函式會呼叫 InitRegistrationInformation，然後呼叫 PcwRegister (請參閱 PcwRegister 以取得詳細數據) 。產生的 InitRegistrationInformation 函式看起來會像這樣：

EXTERN_C FORCEINLINE VOID
InitRegistrationInformationMyCounterset(
    __in_opt PPCW_CALLBACK Callback,
    __in_opt PVOID CallbackContext,
    __out PCW_REGISTRATION_INFORMATION* RegInfo
    )
{
    static const UNICODE_STRING Name = RTL_CONSTANT_STRING(L"My Counterset Name");
    static const PCW_COUNTER_DESCRIPTOR Descriptors[] = {
        { 0, 0, FIELD_OFFSET(MY_COUNTER_DATA, MyData1), RTL_FIELD_SIZE(MY_COUNTER_DATA, MyData1)},
        { 1, 0, FIELD_OFFSET(MY_COUNTER_DATA, MyData2), RTL_FIELD_SIZE(MY_COUNTER_DATA, MyData2)},
    };

#if CTRPP_VERIFY_COUNTER_SIZES

    //
    // Verify that structure member size matches manifest counter size.
    //

    C_ASSERT(RTL_FIELD_SIZE(MY_COUNTER_DATA, MyData1) == sizeof(ULONGLONG));
    C_ASSERT(RTL_FIELD_SIZE(MY_COUNTER_DATA, MyData2) == sizeof(ULONG));

#endif // CTRPP_VERIFY_COUNTER_SIZES

    PAGED_CODE();

    RtlZeroMemory(RegInfo, sizeof(*RegInfo));
    RegInfo->Version = PCW_CURRENT_VERSION;
    RegInfo->Name = &Name;
    RegInfo->CounterCount = RTL_NUMBER_OF(Descriptors);
    RegInfo->Counters = (PCW_COUNTER_DESCRIPTOR*)Descriptors;
    RegInfo->Callback = Callback;
    RegInfo->CallbackContext = CallbackContext;
}

CTRPP 產生的 InitRegistrationInformation 函式會命名為 PrefixInitRegistrationInformationCounterset。 前置詞 通常是空白的，但如果在 CTRPP 命令行上使用參數，則可能會出現 -prefix 。 Counterset 是計數器集的名稱，如指令清單中所指定。產生的 InitRegistrationInformation 函式會使用來自函式參數和指令清單的值，初始化提供的 PCW_REGISTRATION_INFORMATION 結構。

CTRPP 產生的 InitRegistrationInformation 函式可以選擇性地確認結構成員的大小符合指令清單中宣告的大小。根據預設， CTRPP_VERIFY_COUNTER_SIZES 會設定為0，停用這項檢查。若要啟用這項檢查， #define CTRPP_VERIFY_COUNTER_SIZES 1 請先包含 CTRPP 產生的標頭。如果啟用檢查，大小不符將會因為C_ASSERT條件失敗而觸發編譯錯誤。