HW_STREAM_REQUEST_BLOCK結構（strmini.h）

發行項
02/07/2025

數據流類別驅動程式會使用 HW_STREAM_REQUEST_BLOCK 結構，使用minidriver提供的回呼，來回傳遞迷你驅動程序的資訊。

語法

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;

成員

SizeOfThisPacket

指定這個結構的大小，以位元組為單位。

Command

指定要由minidriver回呼執行的作業。類別驅動程式會將SRB_XXX命令代碼傳遞至minidriver回呼。

Status

當 minidriver 完成數據流要求時，它會以要求的狀態代碼填入此成員。請參閱適用於預期使用狀態代碼迷你驅動程式之適當 StrMiniXxx要求例程的檔。

StreamObject

針對數據流導向要求，類別驅動程式會將這個設定為指向指定類別驅動程式所要求之數據流的 HW_STREAM_OBJECT 結構。

HwDeviceExtension

迷你驅動程式裝置延伸模組的指標。迷你驅動程式可以使用這個緩衝區來記錄私人資訊。 minidriver 會在它透過 StreamClassRegisterMinidriver註冊本身時，在 HW_INITIALIZATION_DATA 結構中設定這個緩衝區的大小。類別驅動程式也會將指標傳遞至 HwDeviceExtension 中HW_STREAM_OBJECT、HW_TIME_CONTEXT和 PORT_CONFIGURATION_INFORMATION 結構中傳遞給迷你驅動程式的緩衝區。

SRBExtension

指向類別驅動程式配置給迷你驅動程式在處理此數據流要求區塊時要使用的未初始化緩衝區。此緩衝區會在 minidriver 完成區塊的處理後解除分配（如需詳細資訊，請參閱 StreamClassDeviceNotification 或 StreamClassStreamNotification）。

CommandData

CommandData 是提供給命令程式代碼特定資料的成員聯集。

CommandData.DataBufferArray

KSSTREAM_HEADER 結構的陣列指標。此陣列中的項目數目是在 numberOfBuffers 中指定。每個KSSTREAM_HEADER都會描述一個數據區塊。

當命令程式代碼 SRB_READ_DATA 或 SRB_WRITE_DATA時，會使用此成員。

CommandData.StreamBuffer

指向 HW_STREAM_DESCRIPTOR 結構，迷你驅動程式會填入其支援的核心串流語意描述。

minidriver 會指定 StreamDescriptorSize 中這個緩衝區的大小， 其 PORT_CONFIGURATION_INFORMATION 結構的成員。

當命令程式代碼 SRB_GET_STREAM_INFO時，會使用此成員。

CommandData.StreamState

數據流狀態。如需詳細資訊，請參閱 KSPROPERTY_CONNECTION_STATE。

當命令程式代碼 SRB_GET_STREAM_STATE 或 SRB_SET_STREAM_STATE時，會使用此成員。

CommandData.TimeReference

STREAM_TIME_REFERENCE 結構的指標。

CommandData.PropertyInfo

指向指定屬性取得或設定作業參數的 STREAM_PROPERTY_DESCRIPTOR 結構。

當命令程式代碼 SRB_GET_DEVICE_PROPERTY、SRB_SET_DEVICE_PROPERTY、SRB_GET_STREAM_PROPERTY或 SRB_SET_STREAM_PROPERTY時，會使用此成員。

CommandData.OpenFormat

指定格式之 KSDATAFORMAT 結構的指標。

當命令程式代碼 SRB_OPEN_STREAM 或 SRB_PROPOSE_DATA_FORMAT時，會使用此成員。

CommandData.ConfigInfo

用來初始化裝置之 PORT_CONFIGURATION_INFORMATION 結構的指標

當命令程式代碼 SRB_INITIALIZE_DEVICE時，會使用此成員。

CommandData.MasterClockHandle

現在做為主要時鐘之時鐘物件的句柄。

當命令程式代碼 SRB_OPEN_MASTER_CLOCK 或 SRB_INDICATE_MASTER_CLOCK時，會使用此成員。

CommandData.DeviceState

指定新的電源狀態。

當命令程式代碼 SRB_CHANGE_POWER_STATE時，會使用此成員。

CommandData.IntersectInfo

描述此作業參數之 STREAM_DATA_INTERSECT_INFO 結構的指標。

當命令程式代碼 SRB_GET_DATA_INTERSECTION時，會使用此成員。

CommandData.MethodInfo

要讀取或寫入方法數據的緩衝區指標。

CommandData.FilterTypeIndex

SRB_OPEN_DEVICE_INSTANCE的篩選類型索引。

CommandData.Idle

如果裝置沒有開啟句柄，此成員會設定為 TRUE。如果裝置不再閑置，此成員會設定為 FALSE （裝置的句柄已開啟）。

當命令程式代碼 SRB_NOTIFY_IDLE_STATE時，會使用此成員。

_CommandData

CommandData 是提供給命令程式代碼特定資料的成員聯集。

NumberOfBuffers

如果 Command 是 SRB_READ_DATA 或 SRB_WRITE_DATA，則這會指定 從 commandData.DataBufferArray所指向之位址 KSSTREAM_HEADER 結構陣列中的項目數。否則，這個參數未使用。

TimeoutCounter

此要求逾時之前的秒數。類別驅動程式每秒遞減一次。如果類別驅動程式在 minidriver 完成此要求之前將 TimeoutCount er 遞減為零，它會呼叫 minidriver 的 StrMiniRequestTimeout 例程。如果 minidriver 將此設定為零，要求就不會逾時。

TimeoutOriginal

類別驅動程式會將此值設定為建立 SRB 時，TimeoutCounter 的原始值。

NextSRB

指向另一個數據流要求區塊。 minidriver 可以使用這個成員來將數據流要求區塊排入佇列。

Irp

要求的 IRP 指標。大部分的迷你驅動程式都不需要使用此成員。

Flags

指定要求的類型。類別驅動程式和minidriver可以使用這個成員來判斷類別驅動程式傳遞此資料流要求區塊的回呼。

價值	使用的回呼
沒有	StrMiniReceiveDevicePacket
SRB_HW_FLAGS_STREAM_REQUEST	StrMiniReceiveStreamControlPacket
SRB_HW_FLAGS_DATA_TRANSFER	StrMiniReceiveStreamDataPacket
SRB_HW_FLAGS_STREAM_REQUEST	StrMiniReceiveStreamDataPacket

SRB_HW_FLAGS_STREAM_REQUEST位是針對數據流特定要求設定的（會傳遞至minidriver的 StrMiniReceiveStreamXxxPacket 例程）。系統會針對數據傳輸要求設定SRB_HW_FLAGS_DATA_TRANSFER位（這些要求會傳遞至minidriver）。

HwInstanceExtension

minidriver 實例延伸模組的指標。 minidriver 可以使用這個緩衝區，將全域信息記錄到迷你驅動程式的這個實例。 minidriver 會在它透過 StreamClassRegisterMinidriver註冊本身時，在 HW_INITIALIZATION_DATA 結構中設定這個緩衝區的大小。

NumberOfBytesToTransfer

針對SRB_READ_DATA或SRB_WRITE_DATA要求，要傳輸的位元元組數目。

ActualBytesTransferred

針對控制要求，實際傳輸的位元元組數目。

ScatterGatherBuffer

指向表單KSSCATTER_GATHER結構的陣列：

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

陣列描述迷你驅動程式可用來執行 DMA 的散佈/收集清單。記憶體不需要經過探查、鎖定、對應或排清。數據流類別驅動程式會針對minidriver執行這些專案。

NumberOfPhysicalPages

指定 ScatterGatherBuffer 成員中傳遞的陣列大小。

NumberOfScatterGatherElements

指定 ScatterGatherBuffer所指向的實體項目數目。

Reserved[1]

保留 [1] 欄位供系統使用。請勿使用。

言論

數據流類別驅動程式會將指標傳遞 HW_STREAM_REQUEST_BLOCK至 minidriver StrMiniReceiveStreamDataPacket、StrMiniReceiveStreamControlPacket，以及 StrMiniReceiveDevicePacket 例程。

minidriver 擁有此數據流要求區塊，直到要求逾時或完成要求為止。 minidriver 會透過呼叫 streamClassDeviceNotification 來向類別驅動程式發出訊號，指出它已完成要求（DeviceRequestComplete， pSrb->HwDeviceExtension、 pSRB）用於裝置特定要求，或針對數據流特定要求呼叫 StreamClassStreamNotification（StreamRequestComplete， pSrb->StreamObject， pSrb）。（minidriver 也可以呼叫 StreamClassCompleteRequestAndMarkQueueReady（pSrb）來完成要求。如需詳細資訊，請參閱該例程。

如果類別驅動程式逾時要求，它會呼叫 minidriver 的 StrMiniRequestTimeout 例程，負責終止要求處理。如果 minidriver 將要求排入佇列以供稍後處理，它應該將 TimeoutCounter 成員設定為零，這會防止類別驅動程式逾時要求。當 minidriver 準備好繼續處理要求之後，它應該會將 TimeoutCounter 成員重設為 TimeoutOriginal的值。

要求

要求	價值
標頭	strmini.h （包括 Strmini.h）

共用方式為

HW_STREAM_REQUEST_BLOCK結構（strmini.h）

語法

成員

言論

要求

意見反應

其他資源