ScsiPortWmiSetData function (scsiwmi.h)

Article
10/21/2021

The ScsiPortWmiSetData routine updates the WNODE_ALL_DATA structure within the request context to specify the position and length of the data for an instance.

Note The SCSI port driver and SCSI miniport driver models may be altered or unavailable in the future. Instead, we recommend using the Storport driver and Storport miniport driver models.

Syntax

PVOID ScsiPortWmiSetData(
  [in]      PSCSIWMI_REQUEST_CONTEXT RequestContext,
  [in]      ULONG                    InstanceIndex,
  [in]      ULONG                    DataLength,
  [out]     PULONG                   BufferAvail,
  [in, out] PULONG                   SizeNeeded
);

Parameters

[in] RequestContext

Pointer to a structure of type SCSIWMI_REQUEST_CONTEXT that contains the request context for a WMI SRB.

[in] InstanceIndex

Contains an index that indicates the instance for which the position and length of the instance data are to be specified.

[in] DataLength

Specifies the number of bytes of data required to describe the instance.

[out] BufferAvail

Must contain, on input, the number of bytes of buffer space in the WNODE_ALL_DATA structure that can be used for describing instance names and data. On return, this member contains the number of bytes of buffer space that remain.

There are three SCSI Port WMI routines that return a value for the available buffer size in their BufferAvail parameter:

ScsiPortWmiSetInstanceCount

ScsiPortWmiSetData

ScsiPortWmiSetInstanceName

The miniport driver must call ScsiPortWmiSetInstanceCount first, but after ScsiPortWmiSetInstanceCount has been called, it does not matter in what order the minidriver calls ScsiPortWmiSetData and ScsiPortWmiSetInstanceName. When calling either ScsiPortWmiSetData or ScsiPortWmiSetInstanceName, the value passed to the routine in its BufferAvail parameter must be the same as the value returned in the BufferAvail parameter by the most recently called SCSI Port WMI routine. For instance, suppose the minidriver calls ScsiPortWmiSetInstanceCount first, and this routine returns a value of 1,000 in its BufferAvail parameter. Next, the minidriver calls ScsiPortWmiSetData which returns a value of 500 in its BufferAvail parameter. Finally, the minidriver calls ScsiPortWmiSetInstanceName which returns a value of 200 in its BufferAvail parameter. The initial value of 1,000 must be passed to ScsiPortWmiSetData in BufferAvail, and the value of 500 must be passed to ScsiPortWmiSetInstanceName.

If there is not enough memory available to add new instance data of size DataLength bytes, a zero will be returned in the BufferAvail member.

[in, out] SizeNeeded

Indicates, on input, the number of bytes needed to describe the entire WNODE before adding the descriptive data for the instance specified by InstanceIndex. On return, this member will contain the size of the WNODE, including the data for the new instance.

Return value

The ScsiPortWmiSetData routine returns a pointer to the buffer where the caller can store descriptive information about the instance identified by InstanceIndex. If ScsiPortWmiSetData cannot allocate enough memory for the instance data, or if the WNODE contained within the request context is not of type WNODE_ALL_DATA, ScsiPortWmiSetData returns NULL.

Remarks

The minidriver must call ScsiPortWmiSetInstanceCount before calling ScsiPortWmiSetData.

The parameter RequestContext points to a request context structure, SCSIWMI_REQUEST_CONTEXT, that contains information associated with a Windows Management Instrumentation (WMI) SCSI request block (SRB). The request context structure, in turn, contains one of the WMI WNODE_XXX Structures that is used by the WMI system to pass data between user-mode data consumers and kernel-mode data providers such as drivers.

The ScsiPortWmiSetData routine requires the WNODE structure that is defined within the request context to be of type WNODE_ALL_DATA. This is because ScsiPortWmiSetData can specify the location and length of the data buffers for any of the instances associated with a WMI data block. Unlike the WNODE_SINGLE_INSTANCE structure which contains information about a single instance, the WNODE_ALL_DATA structure contains an array of pointers to buffer areas for multiple instances, and ScsiPortWmiSetData uses the InstanceIndex parameter as an index into this array to initialize the appropriate array element for a particular instance. Each array element, once initialized, contains the size and location of a buffer area for an instance.

The memory allocated for the request context must remain valid until after the miniport driver calls ScsiPortWmiPostProcess, and ScsiPortWmiPostProcess returns the final SRB status and buffer size. If the SRB can pend, the memory for the request context should be allocated from the SRB extension. If the SRB cannot pend, the memory can be allocated from a stack frame that does not go out of scope.

Requirements

Requirement	Value
Target Platform	Desktop
Header	scsiwmi.h (include Miniport.h, Scsi.h)