pcwRegister 函数 (wdm.h)

函数 PcwRegister 创建新的计数器集注册。 大多数开发人员将使用 CTRPP 生成的 RegisterXxx 函数，而不是直接调用此函数。

语法

NTSTATUS PcwRegister(
  [out] PPCW_REGISTRATION             *Registration,
  [in]  PPCW_REGISTRATION_INFORMATION Info
);

参数

[out] Registration

指向PPCW_REGISTRATION的指针。 接收新注册的句柄。 应使用 PcwUnregister 关闭注册。

[in] Info

指向 PCW_REGISTRATION_INFORMATION 结构的指针，该结构包含有关正在注册的计数器集的详细信息。

返回值

PcwRegister 返回以下值之一：

返回代码	说明
STATUS_SUCCESS	计数器集已成功注册。
STATUS_INTEGER_OVERFLOW	此注册公开的计数器数超出了支持的最大数目。
STATUS_NO_MEMORY	没有足够的可用空间来为计数器分配内存。
STATUS_INVALID_PARAMETER_2	在 参数中 Info 发现问题。 有关一些可能的原因，请参阅下文。

PcwRegister 在以下情况下可能会返回 STATUS_INVALID_PARAMETER_2 ：

• 字段 Info->Name->Length 为 0 或不是 的倍数 sizeof(WCHAR)。

• 字段 Info->Version 与此版本的 Windows 不支持的值不匹配。 在 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) 。

• 字段 Info->Flags 包含运行中的 Windows 版本无法识别的值。

注解

提供程序调用此函数以创建新的计数器集注册。 捕获所有输入参数，以便调用方不必保留它们的副本。

默认情况下，新计数器集仅对注册时处于活动状态的服务器接收器可见 (即 PcwRegister ，在调用) 时 PcwRegister ，将新创建的注册与附加到线程的服务器 silo 相关联。 如果在 Windows 10.0.19645 及更高版本上运行 (NTDDI_VERSION >= NTDDI_VERSION_MN) 可以通过将 设置为 并将 PCW_REGISTRATION_INFORMATION::FlagsPcwRegistrationSiloNeutral设置为 PCW_REGISTRATION_INFORMATION::VersionPCW_VERSION_2 来创建对所有服务器接收器可见的计数器集注册。

CTRPP 生成的 RegisterXxx 函数

大多数开发人员不需要直接调用 PcwRegister 。 而是使用 CTRPP 工具编译清单，并使用 CTRPP 生成的标头中的 RegisterXxx 函数。 生成的函数如下所示：

EXTERN_C FORCEINLINE NTSTATUS
RegisterMyCounterset(
    __in_opt PPCW_CALLBACK Callback,
    __in_opt PVOID CallbackContext
    )
{
    PCW_REGISTRATION_INFORMATION RegInfo;

    PAGED_CODE();

    InitRegistrationInformationMyCounterset(Callback, CallbackContext, &RegInfo);

    return PcwRegister(&MyCounterset, &RegInfo);
}

CTRPP 生成的 Register 函数将命名为 前缀寄存器计数器集。 前缀 通常为空，但如果在 CTRPP 命令行上使用参数， -prefix 则可能存在前缀。 Counterset 是清单中指定的计数器集的名称。 生成的 Register 函数将调用 PrefixInitRegistrationInformationCounterset 函数来初始化PCW_REGISTRATION_INFORMATION结构，然后调用 PcwRegister 以创建新的注册，并将句柄存储在 CTRPP 生成的标头MyCounterset中声明的全局 Counterset 变量 (示例中) 。

在某些情况下，CTRPP 生成的 Add 函数可能不合适。

• 如果必须使用 进行 NTDDI_VERSION >= NTDDI_VERSION_FE 编译，但必须在早期版本的 Windows 上运行，则 CTRPP 生成的 Register 函数将不起作用，因为它设置了 RegInfo.Version = PCW_CURRENT_VERSION。 当 时 NTDDI_VERSION >= NTDDI_VERSION_FE， PCW_CURRENT_VERSION 将设置为 PCW_VERSION_2，导致 PcwRegister 返回错误。

• 如果需要支持多个计数器集注册 (例如，支持每个服务器 silo) 单独注册，CTRPP 生成的 Register 函数将不起作用，因为它将返回的句柄存储在全局变量中。

• 如果要创建 silo 中性计数器集注册，CTRPP 生成的 Register 函数将不起作用，因为在调用 PcwRegister之前无法更改 的值RegInfo.Flags。

在这些情况下，请使用如下所示的代码，而不是调用 CTRPP 生成的 Register 函数：

PCW_REGISTRATION_INFORMATION RegInfo;
InitRegistrationInformationMyCounterset(Callback, CallbackContext, &RegInfo);

// Modify RegInfo as needed,
// e.g. RegInfo.Version = PCW_VERSION_1,
// or RegInfo.Flags = PcwRegistrationSiloNeutral.

// If needed, use another variable to store the handle instead of MyCounterset.
Status = PcwRegister(&MyCounterset, &RegInfo);

CTRPP 生成的 InitRegistrationInformationXxx 函数根据清单中的 RegInfo 声明初始化结构。 有关生成的 InitRegistrationInformation 函数的详细信息，请参阅 PCW_REGISTRATION_INFORMATION文档。

如果使用自己的句柄变量而不是 Counterset 来存储句柄，可能还需要直接调用 PcwUnregister 而不是 PcwCreateInstance 使用 CTRPP 生成的 UnregisterXxx 和 CreateXxx 函数。

要求

要求	值
最低受支持的客户端	在 Windows 7 和更高版本的 Windows 中可用。
目标平台	通用
标头	wdm.h (包括 Wdm.h、Ntddk.h)
Library	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	IRQL <= APC_LEVEL

另请参阅

PcwUnregister

_PCW_REGISTRATION_INFORMATION