pcwCreateInstance 函数 (wdm.h)
函数 PcwCreateInstance 创建新的计数器集实例。 大多数开发人员将使用 CTRPP 生成的 CreateXxx 函数，而不是直接调用此函数。
语法
NTSTATUS PcwCreateInstance(
[out] PPCW_INSTANCE *Instance,
[in] PPCW_REGISTRATION Registration,
[in] PCUNICODE_STRING Name,
[in] ULONG Count,
[in] PPCW_DATA Data
);
参数
[out] Instance
用于接收新创建的实例的指针。 应使用 PcwCloseInstance 关闭实例。
[in] Registration
指向拥有此实例的计数器集注册的指针。 注册是使用 PcwRegister 创建的。
[in] Name
指向包含计数器集实例名称的 Unicode 字符串的指针。 这不能为 NULL。
实例 Name 值必须随时间推移保持稳定， (同一逻辑实例应对回调) 的所有调用使用相同的 Name 值，并且必须是唯一的。 如果计数器集注册为单实例，则实例 Name 应为空， (长度为 0 的) 。 如果计数器集注册为多实例，则实例 Name 不应为空。 实例名称匹配不区分大小写，因此 Name 值不应仅因大小写而异。
[in] Count
参数中 Data 提供的描述符数。
[in] Data
提供程序数据块的描述符数组，其中包含此实例的计数器值。 描述符引用的数据块可以随时访问，并且必须保持有效，直到 实例由 PcwCloseInstance 或 PcwUnregister关闭。
返回值
PcwCreateInstance 返回以下值之一：
| 返回代码 | 说明 |
|---|---|
STATUS_SUCCESS |
已成功创建实例。 |
STATUS_INVALID_PARAMETER_4 |
由 Count指定的结构数对已注册的提供程序无效。 |
STATUS_INVALID_BUFFER_SIZE |
其中一个提供程序数据块太小。 例如，假设在调用 PcwRegister 期间，提供程序指定计数器 X 在大小为 4 字节的第一个数据块的偏移量为 100。 如果 对 PcwCreateInstance 的调用指定第一个数据块为 50 个字节，则返回此错误状态。 |
STATUS_INTEGER_OVERFLOW |
由 Count指定的结构的大小会溢出数据缓冲区。 |
注解
计数器集提供程序可以通过两个不同的系统向使用者提供信息：
- 提供程序可以提供一个
PCW_CALLBACK函数，该函数将根据需要由性能计数器库调用以收集数据。 有关此系统的详细信息，请参阅 PCW_CALLBACK文档。 - 提供程序可以使用
PcwCreateInstance和PcwCloseInstance来维护可用实例和相应计数器数据的列表。 此系统易于实现，但灵活性有限。
在提供程序使用此函数之前，提供程序必须调用 函数 PcwRegister 来创建注册。
当新实例到达 (例如，当设备插入) 时，提供程序应为实例分配和初始化数据块，使用实例的名称和数据块调用 PcwCreateInstance ，然后使用实例的计数器值来更新数据块中的值。 当实例变为无效 (例如，当设备拔出) 时，提供程序应调用 PcwCloseInstance 并删除数据块。
提供程序必须维护数据块 (通常位于分页池或非分页池中，) 包含每个实例的当前计数器值。
PcwCreateInstance 将自动为实例分配唯一 ID。 若要为实例 ID 提供特定值，请实现函数 PCW_CALLBACK 而不是使用 PcwCreateInstance。
使用 PcwCloseInstance 函数关闭实例。
CTRPP 生成的 CreateXxx 函数
大多数开发人员不需要直接调用 PcwCreateInstance 。 而是使用 CTRPP 工具编译清单，并使用 CTRPP 生成的标头中的 CreateXxx 函数。 生成的函数如下所示：
EXTERN_C __inline NTSTATUS
CreateMyCounterset(
__deref_out PPCW_INSTANCE *Instance,
__in PCUNICODE_STRING Name,
__in const MY_COUNTER_DATA *MyCounterData
)
{
PCW_DATA Data[1];
PAGED_CODE();
Data[0].Data = MyCounterData;
Data[0].Size = sizeof(MY_COUNTER_DATA);
return PcwCreateInstance(Instance,
MyCounterset,
Name,
1,
Data);
}
CTRPP 生成的 Create 函数将命名为 PrefixCreateCounterset。 前缀 通常为空，但如果在 CTRPP 命令行上使用参数， -prefix 则可能存在前缀。 Counterset 是清单中指定的计数器集的名称。 函数将具有基于清单中定义的结构的数据参数。 函数会将用户提供的数据块 () 包装成结构的数组 PCW_DATA ，然后调用 PcwCreateInstance。 请注意，函数引用示例) 中的 counterset 变量 (MyCounterset ，该变量是一个全局变量，用于保存由 CTRPP 生成的 RegisterXxx 函数初始化的计数器集注册句柄。
要求
| 要求 | 值 |
|---|---|
| 最低受支持的客户端 | 在 Windows 7 和更高版本的 Windows 中可用。 |
| 目标平台 | 通用 |
| 标头 | wdm.h (包括 Wdm.h、Ntddk.h) |
| Library | NtosKrnl.lib |
| DLL | NtosKrnl.exe |
| IRQL | IRQL <= APC_LEVEL |