wdm.h) (PCW_REGISTRATION_INFORMATION 结构

项目
02/27/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 之前的 Windows (NTDDI_VERSION < NTDDI_VERSION_MN) 运行时， 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

此计数器集的计数器的描述符数组。从通过调用 PcwCreateInstance 或 PcwAddInstance提供的数据块中提取计数器值时，将使用描述符中的信息。

Callback

指向可选的 PCW_CALLBACK 回调函数的指针，该函数通知提供程序与此计数器集相关的事件。如果不需要回调，则此字段可能为 NULL， (即，如果计数器集实例将通过和 PcwCloseInstance) 进行管理PcwCreateInstance。

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条件失败而触发编译错误。