HW_STREAM_REQUEST_BLOCK structure (strmini.h)

Artikel
09/01/2022

The stream class driver uses the HW_STREAM_REQUEST_BLOCK structure to pass information to and from the minidriver, using minidriver provided callbacks.

Syntax

typedef struct _HW_STREAM_REQUEST_BLOCK {
  ULONG                           SizeOfThisPacket;
  SRB_COMMAND                     Command;
  NTSTATUS                        Status;
  PHW_STREAM_OBJECT               StreamObject;
  PVOID                           HwDeviceExtension;
  PVOID                           SRBExtension;
  union {
    PKSSTREAM_HEADER                       DataBufferArray;
    PHW_STREAM_DESCRIPTOR                  StreamBuffer;
    KSSTATE                                StreamState;
    PSTREAM_TIME_REFERENCE                 TimeReference;
    PSTREAM_PROPERTY_DESCRIPTOR            PropertyInfo;
    PKSDATAFORMAT                          OpenFormat;
    struct _PORT_CONFIGURATION_INFORMATION *ConfigInfo;
    HANDLE                                 MasterClockHandle;
    DEVICE_POWER_STATE                     DeviceState;
    PSTREAM_DATA_INTERSECT_INFO            IntersectInfo;
    PVOID                                  MethodInfo;
    LONG                                   FilterTypeIndex;
    BOOLEAN                                Idle;
  } CommandData;
  _CommandData                    _CommandData;
  ULONG                           NumberOfBuffers;
  ULONG                           TimeoutCounter;
  ULONG                           TimeoutOriginal;
  struct _HW_STREAM_REQUEST_BLOCK *NextSRB;
  PIRP                            Irp;
  ULONG                           Flags;
  PVOID                           HwInstanceExtension;
  union {
    ULONG NumberOfBytesToTransfer;
    ULONG ActualBytesTransferred;
  };
  PKSSCATTER_GATHER               ScatterGatherBuffer;
  ULONG                           NumberOfPhysicalPages;
  ULONG                           NumberOfScatterGatherElements;
  ULONG                           Reserved[1];
} HW_STREAM_REQUEST_BLOCK, *PHW_STREAM_REQUEST_BLOCK;

Members

SizeOfThisPacket

Specifies the size, in bytes, of this structure.

Command

Specifies the operation to be performed by the minidriver's callback. The class driver passes SRB_XXX command codes to minidriver callbacks.

Status

When the minidriver completes a stream request, it fills this member with the status code of the request. See the documentation for the appropriate StrMiniXxxRequest routine for the status codes minidrivers are expected to use.

StreamObject

For stream oriented requests, the class driver sets this to point to the HW_STREAM_OBJECT structure that specifies the stream the class driver is making a request on.

HwDeviceExtension

Pointer to the minidriver's device extension. The minidriver may use this buffer to record private information. The minidriver sets the size of this buffer in the HW_INITIALIZATION_DATA structure it passes when it registers itself via StreamClassRegisterMinidriver. The class driver also passes pointers to this buffer in the HwDeviceExtension member of the HW_STREAM_OBJECT, HW_TIME_CONTEXT, and PORT_CONFIGURATION_INFORMATION structures it passes to the minidriver.

SRBExtension

Points to an uninitialized buffer the class driver allocates for the minidriver to use while processing this stream request block. This buffer is deallocated once the minidriver completes its handling of the block (see StreamClassDeviceNotification or StreamClassStreamNotification for details).

CommandData

CommandData is a union of members provided for command-code-specific data.

CommandData.DataBufferArray

Pointer to an array of KSSTREAM_HEADER structures. The number of entries in this array is specified in NumberOfBuffers. Each KSSTREAM_HEADER describes one block of data.

This member is used when the command code is SRB_READ_DATA or SRB_WRITE_DATA.

CommandData.StreamBuffer

Points to the HW_STREAM_DESCRIPTOR structure the minidriver fills in with a description of the kernel streaming semantics it supports.

The minidriver specifies the size of this buffer in the StreamDescriptorSize member of its PORT_CONFIGURATION_INFORMATION structure.

This member is used when the command code is SRB_GET_STREAM_INFO.

CommandData.StreamState

The stream state. See KSPROPERTY_CONNECTION_STATE for details.

This member is used when the command code is SRB_GET_STREAM_STATE or SRB_SET_STREAM_STATE.

CommandData.TimeReference

A pointer to a STREAM_TIME_REFERENCE structure.

CommandData.PropertyInfo

Points to the STREAM_PROPERTY_DESCRIPTOR structure that specifies the parameters for the property get or set operation.

This member is used when the command code is SRB_GET_DEVICE_PROPERTY, SRB_SET_DEVICE_PROPERTY, SRB_GET_STREAM_PROPERTY, or SRB_SET_STREAM_PROPERTY.

CommandData.OpenFormat

Pointer to the KSDATAFORMAT structure that specifies the format.

This member is used when the command code is SRB_OPEN_STREAM or SRB_PROPOSE_DATA_FORMAT.

CommandData.ConfigInfo

Pointer to the PORT_CONFIGURATION_INFORMATION structure used to initialize the device

This member is used when the command code is SRB_INITIALIZE_DEVICE.

CommandData.MasterClockHandle

Handle for the clock object that now serves as the master clock.

This member is used when the command code is SRB_OPEN_MASTER_CLOCK or SRB_INDICATE_MASTER_CLOCK.

CommandData.DeviceState

Specifies the new power state.

This member is used when the command code is SRB_CHANGE_POWER_STATE.

CommandData.IntersectInfo

Pointer to a STREAM_DATA_INTERSECT_INFO structure that describes the parameters of this operation.

This member is used when the command code is SRB_GET_DATA_INTERSECTION.

CommandData.MethodInfo

Pointer to a buffer that the method data will be read from or written to.

CommandData.FilterTypeIndex

Filter type index for SRB_OPEN_DEVICE_INSTANCE.

CommandData.Idle

This member is set to TRUE if no open handles to the device remain. This member is set to FALSE if the device is no longer idle (a handle to the device has been opened).

This member is used when the command code is SRB_NOTIFY_IDLE_STATE.

_CommandData

CommandData is a union of members provided for command-code-specific data.

NumberOfBuffers

If Command is either SRB_READ_DATA or SRB_WRITE_DATA, then this specifies the number of entries in the array of KSSTREAM_HEADER structures that begins at the address pointed to by CommandData.DataBufferArray. Otherwise this parameter is unused.

TimeoutCounter

The number of seconds before this request times out. The class driver decrements this once per second. If the class driver decrements TimeoutCounter to zero before the minidriver completes this request, it will call the minidriver's StrMiniRequestTimeout routine. If the minidriver sets this to zero, the request does not time out.

TimeoutOriginal

The class driver sets this to the original value of TimeoutCounter upon the creation of the SRB.

NextSRB

Points to another stream request block. The minidriver can use this member to queue stream request blocks.

Irp

Pointer to the IRP for the request. Most minidrivers do not need to use this member.

Flags

Specifies the type of request. The class driver and the minidriver can use this member to determine which callback the class driver passed this stream request block to.

Value	Callback used
None	StrMiniReceiveDevicePacket
SRB_HW_FLAGS_STREAM_REQUEST	StrMiniReceiveStreamControlPacket
SRB_HW_FLAGS_DATA_TRANSFER	StrMiniReceiveStreamDataPacket
SRB_HW_FLAGS_STREAM_REQUEST	StrMiniReceiveStreamDataPacket

SRB_HW_FLAGS_STREAM_REQUEST bit is set for stream-specific requests (which are passed to the minidriver's StrMiniReceiveStreamXxxPacket routines). The SRB_HW_FLAGS_DATA_TRANSFER bit is set for data transfer requests (which are passed to the minidriver).

HwInstanceExtension

Pointer to the minidriver's instance extension. The minidriver may use this buffer to record private information global to this instance of the minidriver. The minidriver sets the size of this buffer in the HW_INITIALIZATION_DATA structure it passes when it registers itself via StreamClassRegisterMinidriver.

NumberOfBytesToTransfer

For a SRB_READ_DATA or SRB_WRITE_DATA request, the number of bytes to be transferred.

ActualBytesTransferred

For control requests, the number of bytes actually transferred.

ScatterGatherBuffer

Points to an array of KSSCATTER_GATHER structures, of the form:

typedef struct {
    PHYSICAL_ADDRESS PhysicalAddress;
    ULONG Length;
} KSSCATTER_GATHER, *PKSSCATTER_GATHER;

The array describes a scatter/gather list that can be used by the minidriver to do DMA. The memory does not need to be probed, locked, mapped, or flushed. The stream class driver performs these for the minidriver.

NumberOfPhysicalPages

Specifies the size of the array passed in the ScatterGatherBuffer member.

NumberOfScatterGatherElements

Specifies the number of physical elements pointed to by ScatterGatherBuffer.

Reserved[1]

The Reserved[1] field is reserved for system use. Do not use.

Remarks

The stream class driver passes pointers to HW_STREAM_REQUEST_BLOCK structures to the minidriver's StrMiniReceiveStreamDataPacket, StrMiniReceiveStreamControlPacket, and StrMiniReceiveDevicePacket routines.

The minidriver owns this stream request block until the request times out or it completes the request. The minidriver signals to the class driver that it has completed the request by calling StreamClassDeviceNotification(DeviceRequestComplete, pSrb->HwDeviceExtension, pSRB) for device-specific requests, or calling StreamClassStreamNotification(StreamRequestComplete, pSrb->StreamObject, pSrb) for stream-specific requests. (The minidriver can also complete a request by calling StreamClassCompleteRequestAndMarkQueueReady(pSrb). See that routine for details.)

If the class driver times out the request, it will call the minidriver's StrMiniRequestTimeout routine, which has the responsibility of terminating processing of the request. If the minidriver queues a request for later processing, it should set the TimeoutCounter member to zero, which will prevent the class driver from timing out the request. Once the minidriver is ready to resume processing the request, it should reset the TimeoutCounter member to the value of TimeoutOriginal.

Requirements

Requirement	Value
Header	strmini.h (include Strmini.h)

Delen via

HW_STREAM_REQUEST_BLOCK structure (strmini.h)

Syntax

Members

Remarks

Requirements

Feedback

Aanvullende resources