HW_STREAM_REQUEST_BLOCK-Struktur (strmini.h)

Artikel
02/29/2024

Der Streamklassentreiber verwendet die HW_STREAM_REQUEST_BLOCK-Struktur , um Informationen an und vom Minidriver zu übergeben, wobei die von Minidriver bereitgestellten Rückrufe verwendet werden.

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;

Member

SizeOfThisPacket

Gibt die Größe dieser Struktur in Bytes an.

Command

Gibt den Vorgang an, der vom Rückruf des Minidrivers ausgeführt werden soll. Der Klassentreiber übergibt SRB_XXX Befehlscodes an Minidriver-Rückrufe.

Status

Wenn der Minidriver eine Streamanforderung abschließt, füllt er diesen Member mit dem status Code der Anforderung aus. In der Dokumentation finden Sie die entsprechende StrMiniXxx-Anforderungsroutine für die status Codes, von denen erwartet wird, dass Minidriver verwendet werden.

StreamObject

Bei streamorientierten Anforderungen legt der Klassentreiber dies so fest, dass er auf die HW_STREAM_OBJECT-Struktur verweist, die den Stream angibt, für den der Klassentreiber eine Anforderung sendet.

HwDeviceExtension

Zeiger auf die Geräteerweiterung des Minidrivers. Der Minidriver kann diesen Puffer verwenden, um private Informationen aufzuzeichnen. Der Minidriver legt die Größe dieses Puffers in der HW_INITIALIZATION_DATA Struktur fest, die er übergibt, wenn er sich über StreamClassRegisterMinidriver registriert. Der Klassentreiber übergibt auch Zeiger an diesen Puffer im HwDeviceExtension-Member des HW_STREAM_OBJECT, HW_TIME_CONTEXT und PORT_CONFIGURATION_INFORMATION Strukturen, die er an den Minidriver übergibt.

SRBExtension

Zeigt auf einen nicht initialisierten Puffer, den der Klassentreiber für den Minidriver zuweist, der während der Verarbeitung dieses Streamanforderungsblocks verwendet werden soll. Dieser Puffer wird zugeordnet, sobald der Minidriver die Verarbeitung des Blocks abgeschlossen hat (ausführliche Informationen finden Sie unter StreamClassDeviceNotification oder StreamClassStreamNotification ).

CommandData

CommandData ist eine Union von Elementen, die für befehlscodespezifische Daten bereitgestellt werden.

CommandData.DataBufferArray

Zeiger auf ein Array von KSSTREAM_HEADER Strukturen. Die Anzahl der Einträge in diesem Array wird in NumberOfBuffers angegeben. Jede KSSTREAM_HEADER beschreibt einen Datenblock.

Dieses Element wird verwendet, wenn der Befehlscode SRB_READ_DATA oder SRB_WRITE_DATA ist.

CommandData.StreamBuffer

Zeigt auf die HW_STREAM_DESCRIPTOR Struktur, die der Minidriver mit einer Beschreibung der vom Minidriver unterstützten Kernelstreamingsemantik ausfüllt.

Der Minidriver gibt die Größe dieses Puffers im StreamDescriptorSize-Member seiner PORT_CONFIGURATION_INFORMATION-Struktur an.

Dieses Element wird verwendet, wenn der Befehlscode SRB_GET_STREAM_INFO wird.

CommandData.StreamState

Der Streamstatus. Weitere Informationen finden Sie unter KSPROPERTY_CONNECTION_STATE .

Dieses Element wird verwendet, wenn der Befehlscode SRB_GET_STREAM_STATE oder SRB_SET_STREAM_STATE ist.

CommandData.TimeReference

Ein Zeiger auf eine STREAM_TIME_REFERENCE-Struktur.

CommandData.PropertyInfo

Zeigt auf die STREAM_PROPERTY_DESCRIPTOR-Struktur , die die Parameter für den Vorgang zum Abrufen oder Festlegen der Eigenschaft angibt.

Dieses Element wird verwendet, wenn der Befehlscode SRB_GET_DEVICE_PROPERTY, SRB_SET_DEVICE_PROPERTY, SRB_GET_STREAM_PROPERTY oder SRB_SET_STREAM_PROPERTY ist.

CommandData.OpenFormat

Zeiger auf die KSDATAFORMAT-Struktur , die das Format angibt.

Dieses Element wird verwendet, wenn der Befehlscode SRB_OPEN_STREAM oder SRB_PROPOSE_DATA_FORMAT ist.

CommandData.ConfigInfo

Zeiger auf die PORT_CONFIGURATION_INFORMATION Struktur, die zum Initialisieren des Geräts verwendet wird

Dieses Element wird verwendet, wenn der Befehlscode SRB_INITIALIZE_DEVICE wird.

CommandData.MasterClockHandle

Handle für das Uhrobjekt, das jetzt als master Uhr dient.

Dieses Element wird verwendet, wenn der Befehlscode SRB_OPEN_MASTER_CLOCK oder SRB_INDICATE_MASTER_CLOCK ist.

CommandData.DeviceState

Gibt den neuen Energiestatus an.

Dieses Element wird verwendet, wenn der Befehlscode SRB_CHANGE_POWER_STATE wird.

CommandData.IntersectInfo

Zeiger auf eine STREAM_DATA_INTERSECT_INFO-Struktur , die die Parameter dieses Vorgangs beschreibt.

Dieses Element wird verwendet, wenn der Befehlscode SRB_GET_DATA_INTERSECTION wird.

CommandData.MethodInfo

Zeiger auf einen Puffer, aus dem die Methodendaten gelesen oder geschrieben werden.

CommandData.FilterTypeIndex

Filtertypindex für SRB_OPEN_DEVICE_INSTANCE.

CommandData.Idle

Dieser Member wird auf TRUE festgelegt, wenn keine geöffneten Handles für das Gerät verbleiben. Dieser Member ist auf FALSE festgelegt, wenn sich das Gerät nicht mehr im Leerlauf befindet (ein Handle für das Gerät wurde geöffnet).

Dieses Element wird verwendet, wenn der Befehlscode SRB_NOTIFY_IDLE_STATE wird.

_CommandData

CommandData ist eine Union von Elementen, die für befehlscodespezifische Daten bereitgestellt werden.

NumberOfBuffers

Wenn Command entweder SRB_READ_DATA oder SRB_WRITE_DATA ist, gibt dies die Anzahl der Einträge im Array der KSSTREAM_HEADER Strukturen an, die an der Adresse beginnt, auf die von CommandData.DataBufferArray verwiesen wird. Andernfalls wird dieser Parameter nicht verwendet.

TimeoutCounter

Die Anzahl der Sekunden, bis diese Anforderung ein Zeitüberschreitungsintervall hat. Der Klassentreiber dekrementiert dies einmal pro Sekunde. Wenn der Klassentreiber TimeoutCounter auf null erhöht, bevor der Minidriver diese Anforderung abgeschlossen hat, ruft er die StrMiniRequestTimeout-Routine des Minidrivers auf. Wenn der Minidriver diesen Wert auf 0 festlegt, tritt für die Anforderung kein Timeout auf.

TimeoutOriginal

Der Klassentreiber legt dies bei der Erstellung des SRB auf den ursprünglichen Wert von TimeoutCounter fest.

NextSRB

Zeigt auf einen anderen Streamanforderungsblock. Der Minidriver kann diesen Member verwenden, um Streamanforderungsblöcke in die Warteschlange zu stellen.

Irp

Zeiger auf den IRP für die Anforderung. Die meisten Minidriver müssen diesen Member nicht verwenden.

Flags

Gibt den Typ der Anforderung an. Der Klassentreiber und der Minitreiber können dieses Element verwenden, um zu bestimmen, an welchen Rückruf der Klassentreiber diesen Streamanforderungsblock übergeben hat.

Wert	Verwendeter Rückruf
Keine	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 für streamspezifische Anforderungen festgelegt ist (die an die StrMiniReceiveStreamXxx-Paketroutinen des Minidrivers übergeben werden). Das SRB_HW_FLAGS_DATA_TRANSFER Bits wird für Datenübertragungsanforderungen festgelegt (die an den Minidriver übergeben werden).

HwInstanceExtension

Zeiger auf die instance Erweiterung des Minidrivers. Der Minidriver kann diesen Puffer verwenden, um private Informationen global für diese instance des Minidrivers aufzuzeichnen. Der Minidriver legt die Größe dieses Puffers in der HW_INITIALIZATION_DATA Struktur fest, die er übergibt, wenn er sich über StreamClassRegisterMinidriver registriert.

NumberOfBytesToTransfer

Bei einer SRB_READ_DATA- oder SRB_WRITE_DATA-Anforderung die Anzahl der zu übertragenden Bytes.

ActualBytesTransferred

Bei Steuerungsanforderungen die Anzahl der tatsächlich übertragenen Bytes.

ScatterGatherBuffer

Zeigt auf ein Array von KSSCATTER_GATHER Strukturen der Form:

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

Das Array beschreibt eine Punkt-/Sammlungsliste, die vom Minidriver zum Ausführen von DMA verwendet werden kann. Der Arbeitsspeicher muss nicht überprüft, gesperrt, zugeordnet oder geleert werden. Der Streamklassentreiber führt diese für den Minidriver aus.

NumberOfPhysicalPages

Gibt die Größe des Arrays an, das im ScatterGatherBuffer-Element übergeben wird.

NumberOfScatterGatherElements

Gibt die Anzahl der physischen Elemente an, auf die von ScatterGatherBuffer verwiesen wird.

Reserved[1]

Das Feld Reserviert[1] ist für die Systemverwendung reserviert. Nicht verwenden.

Hinweise

Der Streamklassentreiber übergibt Zeiger an HW_STREAM_REQUEST_BLOCK Strukturen an die Routinen StrMiniReceiveStreamDataPacket, StrMiniReceiveStreamControlPacket und StrMiniReceiveDevicePacket des Minidrivers.

Der Minidriver besitzt diesen Streamanforderungsblock, bis die Anforderung ein Timeout aufweist oder die Anforderung abgeschlossen wird. Der Minidriver signalisiert dem Klassentreiber, dass er die Anforderung abgeschlossen hat, indem er StreamClassDeviceNotification(DeviceRequestComplete, pSrb-HwDeviceExtension>, pSRB) für gerätespezifische Anforderungen aufruft oder StreamClassStreamNotification(StreamRequestComplete, pSrb-StreamObject>, pSrb) für streamspezifische Anforderungen aufruft. (Der Minidriver kann auch eine Anforderung ausführen, indem er StreamClassCompleteRequestAndMarkQueueReady(pSrb) aufruft. Weitere Informationen finden Sie in dieser Routine.)

Wenn der Klassentreiber ein Timeout der Anforderung aufweist, ruft er die StrMiniRequestTimeout-Routine des Minidrivers auf, die für das Beenden der Verarbeitung der Anforderung verantwortlich ist. Wenn der Minitreiber eine Anforderung für die spätere Verarbeitung in die Warteschlange stellt, sollte er den TimeoutCounter-Member auf 0 festlegen, was verhindert, dass der Klassentreiber die Anforderung zeitlich ausrichtet. Sobald der Minidriver bereit ist, die Verarbeitung der Anforderung fortzusetzen, sollte er das TimeoutCounter-Element auf den Wert von TimeoutOriginal zurücksetzen.

Anforderungen

Anforderung	Wert
Header	strmini.h (include Strmini.h)