Export (0) Print
Expand All

DpWmiSetDataItem routine

The DpWmiSetDataItem routine changes a single data item in an instance of a data block. This routine is optional.

Syntax


NTSTATUS DpWmiSetDataItem(
  _In_  PDEVICE_OBJECT DeviceObject,
  _In_  PIRP Irp,
  _In_  ULONG GuidIndex,
  _In_  ULONG InstanceIndex,
  _In_  ULONG DataItemId,
  _In_  ULONG BufferSize,
  _In_  PUCHAR Buffer
);

Parameters

DeviceObject [in]

Pointer to the driver's WDM DEVICE_OBJECT structure.

Irp [in]

Pointer to the IRP.

GuidIndex [in]

Specifies the data block by supplying a zero-based index into the list of GUIDs that the driver provided in the WMILIB_CONTEXT structure it passed to WmiSystemControl.

InstanceIndex [in]

If the block specified by GuidIndex has multiple instances, InstanceIndex is a zero-based value that specifies the instance.

DataItemId [in]

Specifies the ID of the data item to set.

BufferSize [in]

Specifies the size in bytes of the buffer at Buffer.

Buffer [in]

Pointer to a buffer that contains the new value for the data item.

Return value

DpWmiSetDataItem returns STATUS_SUCCESS or an appropriate error code such as the following:

STATUS_WMI_INSTANCE_NOT_FOUND
STATUS_WMI_ITEMID_NOT_FOUND
STATUS_WMI_GUID_NOT_FOUND
STATUS_WMI_READ_ONLY
STATUS_WMI_SET_FAILURE

Remarks

WMI calls a driver's DpWmiSetDataItem routine after the driver calls WmiSystemControl in response to an IRP_MN_CHANGE_SINGLE_ITEM request.

Do not implement DpWmiSetDataItem unless you are sure that a system-supplied user-mode component requires this capability. If you implement a DpWmiSetDataItem routine, the driver must place the routine's address in the SetWmiDataItem member of the WMILIB_CONTEXT structure that it passes to WmiSystemControl. If you do not implement a DpWmiSetDataItem routine, the driver must set SetWmiDataItem to NULL. In the latter case, WMI returns STATUS_READ_ONLY to the caller.

The driver is responsible for validating all input arguments. Specifically, the driver must do the following:

  • Verify that the GuidIndex value is between zero and GuidCount-1, based on the GuidCount member of the WMILIB_CONTEXT structure.

  • Verify that the driver has not flagged the specified data block for removal. If the driver recently specified the WMIREG_FLAG_REMOVE_GUID flag in a WMIGUIDREGINFO structure that is contained in a WMILIB_CONTEXT structure, it is possible for a set request to arrive before the removal occurs.

  • Verify that the InstanceIndex value is within the range of instance indexes that are supported by the driver for the data block.

  • Verify that the DataItemId value is within the range of data item identifiers that are supported by the driver for the data block.

  • Verify that Buffer and BufferSize describe a valid-sized data item, and that the contents of the buffer are valid for the data item.

  • Verify that the specified data item is one for which the driver allows caller-initiated modifications. In other words, the driver should not allow modifications to data items that you intended to be read-only.

Do not assume the thread context is that of the initiating user-mode application—a higher-level driver might have changed it.

This routine can be pageable.

For more information about implementing this routine, see Calling WmiSystemControl to Handle WMI IRPs.

Requirements

Header

Wmilib.h (include Wmilib.h)

IRQL

Called at PASSIVE_LEVEL.

See also

IRP_MN_CHANGE_SINGLE_ITEM
WMILIB_CONTEXT
WmiSystemControl

 

 

Send comments about this topic to Microsoft

Show:
© 2014 Microsoft