HW_STREAM_REQUEST_BLOCK

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

typedef struct _HW_STREAM_REQUEST_BLOCK {
    ULONG              SizeOfThisPacket;
    SRB_COMMAND        Command;
    NTSTATUS           Status;
    PHW_STREAM_OBJECT  StreamObject;
    PVOID              HwDeviceExtension;
    PVOID              SRBExtension;
 
    union _CommandData {
        PKSSTREAM_HEADER              DataBufferArray;
        PHW_STREAM_DESCRIPTOR         StreamBuffer;
        KSSTATE                       StreamState;
        PSTREAM_PROPERTY_DESCRIPTOR   PropertyInfo;
        PKSDATAFORMAT                 OpenFormat;
        struct _PORT_CONFIGURATION_INFORMATION  *ConfigInfo;
        HANDLE                        MasterClockHandle;
        DEVICE_POWER_STATE            DeviceState;
        PSTREAM_DATA_INTERSECT_INFO   IntersectInfo;
    } 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               Reserved[2];
} 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. The following demonstrates the correspondence between members and command codes.

Member	Command code	Description
DataBufferArray	SRB_READ_DATA SRB_WRITE_DATA	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.
StreamBuffer	SRB_GET_STREAM_INFO	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.
StreamState	SRB_GET_STREAM_STATE SRB_SET_STREAM_STATE	The stream state. See KSPROPERTY_CONNECTION_STATE for details.
PropertyInfo	SRB_GET_DEVICE_PROPERTY SRB_SET_DEVICE_PROPERTY SRB_GET_STREAM_PROPERTY SRB_SET_STREAM_PROPERTY	Points to the STREAM_PROPERTY_DESCRIPTOR structure that specifies the parameters for the property get or set operation.
OpenFormat	SRB_OPEN_STREAM SRB_PROPOSE_DATA_FORMAT	Pointer to the KSDATAFORMAT structure that specifies the format.
ConfigInfo	SRB_INITIALIZE_DEVICE	Pointer to the PORT_CONFIGURATION_INFORMATION structure used to initialize the device
MasterClockHandle	SRB_OPEN_MASTER_CLOCK SRB_INDICATE_MASTER_CLOCK	Handle for the clock object that now serves as the master clock.
DeviceState	SRB_CHANGE_POWER_STATE	Specifies the new power state.
IntersectInfo	SRB_GET_DATA_INTERSECTION	Pointer to a STREAM_DATA_INTERSECT_INFO structure that describes the parameters of this operation.

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 | 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's

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.

Reserved[2]

Reserved for system use. Do not use.

Headers

Declared in strmini.h. Include strmini.h.

Comments

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.