WMI_SET_DATAITEM_CALLBACK回调函数 (wmilib.h)

  • 项目

DpWmiSetDataItem 例程更改数据块实例中的单个数据项。 此例程是可选的。

语法

WMI_SET_DATAITEM_CALLBACK WmiSetDataitemCallback;

NTSTATUS WmiSetDataitemCallback(
  [in] PDEVICE_OBJECT DeviceObject,
  [in] PIRP Irp,
  [in] ULONG GuidIndex,
  [in] ULONG InstanceIndex,
  [in] ULONG DataItemId,
  [in] ULONG BufferSize,
  [in] PUCHAR Buffer
)
{...}

参数

[in] DeviceObject

指向驱动程序的 WDM DEVICE_OBJECT 结构的指针。

[in] Irp

指向 IRP 的指针。

[in] GuidIndex

通过将从零开始的索引提供给驱动程序在传递给 WmiSystemControl 的 WMILIB_CONTEXT 结构中提供的 GUID 列表中来指定数据块。

[in] InstanceIndex

如果 GuidIndex 指定的块具有多个实例， 则 InstanceIndex 是从零开始的值，用于指定实例。

[in] DataItemId

指定要设置的数据项的 ID。

[in] BufferSize

指定 Buffer 处缓冲区的大小（以字节为单位）。

[in] Buffer

指向包含数据项的新值的缓冲区的指针。

返回值

DpWmiSetDataItem 返回STATUS_SUCCESS或相应的错误代码，如下所示：

注解

WMI 在驱动程序调用 WmiSystemControl 以响应IRP_MN_CHANGE_SINGLE_ITEM请求后调用驱动程序的 DpWmiSetDataItem 例程。

除非确定系统提供的用户模式组件需要此功能，否则不要实现 DpWmiSetDataItem 。 如果实现 DpWmiSetDataItem 例程，驱动程序必须将例程的地址放置在它传递给 WmiSystemControl 的 WMILIB_CONTEXT 结构的 SetWmiDataItem 成员中。 如果不实现 DpWmiSetDataItem 例程，驱动程序必须将 SetWmiDataItem 设置为 NULL。 在后一种情况下，WMI 将STATUS_READ_ONLY返回给调用方。

驱动程序负责验证所有输入参数。 具体而言，驱动程序必须执行以下操作：

  • 根据 WMILIB_CONTEXT 结构的 GuidCount 成员，验证 GuidIndex 值是否介于 0 和 GuidCount-1 之间。
  • 验证驱动程序是否未标记要删除的指定数据块。 如果驱动程序最近在 WMILIB_CONTEXT 结构中包含的 WMIGUIDREGINFO 结构中指定 了WMIREG_FLAG_REMOVE_GUID 标志，则设置请求可能在删除发生之前到达。
  • 验证 InstanceIndex 值是否在数据块驱动程序支持的实例索引范围内。
  • 验证 DataItemId 值是否在数据块驱动程序支持的数据项标识符范围内。
  • 验证 Buffer 和 BufferSize 描述有效大小的数据项，以及缓冲区的内容是否对数据项有效。
  • 验证指定的数据项是否为驱动程序允许调用方发起的修改的数据项。 换句话说，驱动程序不应允许对要为只读的数据项进行修改。
不要假设线程上下文是发起的用户模式应用程序的上下文，更高级别的驱动程序可能已更改它。

此例程可以分页。

有关实现此例程的详细信息，请参阅 调用 WmiSystemControl 以处理 WMI IRP。

要求

要求 值
目标平台 桌面
标头 wmilib.h (包括 Wmilib.h)
IRQL 在 PASSIVE_LEVEL 调用。

另请参阅

IRP_MN_CHANGE_SINGLE_ITEM

WMILIB_CONTEXT

WmiSystemControl