WMI_SET_DATABLOCK_CALLBACK callback function (wmilib.h)

The DpWmiSetDataBlock routine changes all data items in a single instance of a data block. This routine is optional.

Syntax

WMI_SET_DATABLOCK_CALLBACK WmiSetDatablockCallback;

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

Parameters

[in] DeviceObject

Pointer to the driver's WDM DEVICE_OBJECT structure.

[in] Irp

Pointer to the IRP.

[in] GuidIndex

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

[in] InstanceIndex

If the block specified by GuidIndex has multiple instances, InstanceIndex specifies the instance.

[in] BufferSize

Specifies the size in bytes of the buffer at Buffer.

[in] Buffer

Pointer to a buffer that contains new values for the instance.

Return value

DpWmiSetDataBlock returns STATUS_SUCCESS or an appropriate error status such as the following:

If the driver cannot complete the request immediately, it can return STATUS_PENDING.

Remarks

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

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 Buffer and BufferSize describe a valid-sized data block, including any padding that exists between data items, and that the contents of the buffer are valid for the data block.
• Verify that the specified data block is one for which the driver allows caller-initiated modifications. In other words, the driver should not allow modifications to data blocks that you intended to be read-only.

If a driver implements a DpWmiSetDataBlock routine, the driver must place the routine's address in the SetWmiDataBlock member of the WMILIB_CONTEXT structure that it passes to WmiSystemControl. If a driver does not implement a DpWmiSetDataBlock routine, it must set SetWmiDataBlock to NULL. In the latter case, WMI returns STATUS_READ_ONLY to the caller.

This routine can be pageable.

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

Requirements

See also

IRP_MN_CHANGE_SINGLE_INSTANCE

WMILIB_CONTEXT

WmiSystemControl