HW_STREAM_REQUEST_BLOCK structure (strmini.h)
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) |