pcwAddInstance 函数 (wdm.h)

  • 项目

函数 PcwAddInstance 将计数器集的指定实例添加到使用者缓冲区。 大多数开发人员将使用 CTRPP 生成的 AddXxx 函数，而不是直接调用此函数。 有关详细信息，请参阅下面的“备注”。

语法

NTSTATUS PcwAddInstance(
  [in] PPCW_BUFFER      Buffer,
  [in] PCUNICODE_STRING Name,
  [in] ULONG            Id,
  [in] ULONG            Count,
  [in] PPCW_DATA        Data
);

参数

[in] Buffer

将向其添加计数器集实例的系统托管缓冲区的句柄。 当缓冲区来自通知时 PcwCallbackEnumerateInstances ， PcwAddInstance 将仅记录实例的名称和 ID。 当缓冲区来自通知时 PcwCallbackCollectData ， PcwAddInstance 将记录实例) 的名称、ID 和数据 (计数器值。

[in] Name

指向包含计数器集实例名称的 Unicode 字符串的指针。 这不能为 NULL。

实例 Name 值必须随时间推移保持稳定， (同一逻辑实例应对回调) 的所有调用使用相同的 Name 值，并且必须是唯一的。 如果计数器集注册为单实例，则实例 Name 应为空 (长度为 0 的) 。 如果计数器集注册为多实例，则实例 Name 不应为空。 实例名称匹配不区分大小写，因此 Name 值不应仅因大小写而异。

[in] Id

一个数值，指定 Id 与计数器集实例关联的 (标识符) 。

实例 Id 值必须随时间推移保持稳定， (同一实例应对回调) 的所有调用使用相同的 Id 值，应是唯一 (例如，不要对) 的所有实例使用 0，并且应小于0xFFFFFFFE (不用于 PCW_ANY_INSTANCE_ID) 的任何实例。 如果可能，实例 Id 应有意义 (例如，进程计数器集可能使用 PID 作为 Id) 而不是任意 (例如序列号) 。

[in] Count

参数中 Data 提供的描述符数。

[in] Data

包含此实例的计数器值的提供程序数据块的描述符数组。

返回值

PcwAddInstance 返回以下值之一：

返回代码 说明
STATUS_SUCCESS 实例已成功添加到缓冲区。
STATUS_INVALID_BUFFER_SIZE 其中一个提供程序数据块太小。 例如，假设在调用 PcwRegister 期间，提供程序指定计数器 X 的偏移量为 4 字节的第一个数据块的偏移量为 100。 如果对 PcwAddInstance 的调用指定第一个数据块为 50 字节，则返回此错误状态。

注解

当PcwAddInstance通知类型为 PcwCallbackEnumerateInstances 或 PcwCallbackCollectData时，提供程序定义的PCW_CALLBACK例程应调用 函数。 Buffer要使用的 来自Info例程的 PCW_CALLBACK 参数，例如 Info->EnumerateInstances.Buffer 或 Info->CollectData.Buffer。

为 PcwCallbackEnumerateInstances 通知调用 时， PcwAddInstance 将 Name 和 Id 值添加到缓冲区。 当为 PcwCallbackCollectData 通知调用时， PcwAddInstance 将 Name、 Id和 计数器数据值添加到缓冲区。

CTRPP 生成的 Add*** 函数

大多数开发人员不需要直接调用 PcwAddInstance 。 相反，他们将使用 CTRPP 工具编译清单，并使用 CTRPP 生成的标头中的 Add***函数。 生成的函数如下所示：

EXTERN_C __inline NTSTATUS
AddMyCounterset(
    __in PPCW_BUFFER Buffer,
    __in PCUNICODE_STRING Name,
    __in ULONG Id,
    __in_opt const MY_COUNTER_DATA *MyCounterData
    )
{
    PCW_DATA Data[1];

    PAGED_CODE();

    Data[0].Data = MyCounterData;
    Data[0].Size = sizeof(MY_COUNTER_DATA);

    return PcwAddInstance(Buffer,
                          Name,
                          Id,
                          1,
                          Data);
}

CTRPP 生成的 Add 函数将命名为 PrefixAddCounterset。 前缀 通常为空，但如果在 CTRPP 命令行上使用参数， -prefix 则可能是存在的。 Counterset 是清单中指定的计数器集的名称。 函数将具有基于清单中定义的结构的 Data 参数。 函数会将用户提供的数据块 () 包装到结构数组中 PCW_DATA ，然后调用 PcwAddInstance。

要求

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

另请参阅

PCW_CALLBACK回调函数