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

另请参阅

PcwCloseInstance 函数

PcwRegister 函数