Partager via

structure HW_STREAM_REQUEST_BLOCK (strmini.h)

  • Article

Le pilote de classe de flux utilise la structure HW_STREAM_REQUEST_BLOCK pour transmettre des informations à et depuis le minidriver, à l’aide de rappels fournis par minidriver.

Syntaxe

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;

Membres

SizeOfThisPacket

Spécifie la taille, en octets, de cette structure.

Command

Spécifie l’opération à effectuer par le rappel du minidriver. Le pilote de classe passe SRB_XXX codes de commande aux rappels minidriver.

Status

Lorsque le minidriver termine une demande de flux, il remplit ce membre avec le code d’état de la demande. Consultez la documentation relative à la routine StrMiniXxxRequest routine pour les minidrivers des codes d’état.

StreamObject

Pour les requêtes orientées flux, le pilote de classe définit ceci pour pointer vers la structure HW_STREAM_OBJECT qui spécifie le flux sur lequel le pilote de classe effectue une requête.

HwDeviceExtension

Pointeur vers l’extension d’appareil du minidriver. Le minidriver peut utiliser cette mémoire tampon pour enregistrer des informations privées. Le minidriver définit la taille de cette mémoire tampon dans la structure HW_INITIALIZATION_DATA qu’il transmet lorsqu’il s’inscrit via StreamClassRegisterMinidriver. Le pilote de classe transmet également des pointeurs vers cette mémoire tampon dans le HwDeviceExtension membre du HW_STREAM_OBJECT, HW_TIME_CONTEXTet PORT_CONFIGURATION_INFORMATION les structures qu’il transmet au minidriver.

SRBExtension

Pointe vers une mémoire tampon non initialisée que le pilote de classe alloue pour le minidriver à utiliser lors du traitement de ce bloc de requête de flux. Cette mémoire tampon est libérée une fois que le minidriver termine sa gestion du bloc (voir StreamClassDeviceNotification ou StreamClassStreamNotification pour plus d’informations).

CommandData

CommandData est une union de membres fournis pour les données spécifiques au code de commande.

CommandData.DataBufferArray

Pointeur vers un tableau de structures KSSTREAM_HEADER. Le nombre d’entrées de ce tableau est spécifié dans NumberOfBuffers. Chaque KSSTREAM_HEADER décrit un bloc de données.

Ce membre est utilisé lorsque le code de commande est SRB_READ_DATA ou SRB_WRITE_DATA.

CommandData.StreamBuffer

Pointe vers la structure HW_STREAM_DESCRIPTOR que le minidriver remplit avec une description de la sémantique de diffusion en continu du noyau qu’il prend en charge.

Le minidriver spécifie la taille de cette mémoire tampon dans la StreamDescriptorSize membre de sa structure PORT_CONFIGURATION_INFORMATION.

Ce membre est utilisé lorsque le code de commande est SRB_GET_STREAM_INFO.

CommandData.StreamState

État du flux. Consultez KSPROPERTY_CONNECTION_STATE pour plus d’informations.

Ce membre est utilisé lorsque le code de commande est SRB_GET_STREAM_STATE ou SRB_SET_STREAM_STATE.

CommandData.TimeReference

Pointeur vers une structure STREAM_TIME_REFERENCE.

CommandData.PropertyInfo

Pointe vers la structure STREAM_PROPERTY_DESCRIPTOR qui spécifie les paramètres de l’opération get ou set de la propriété.

Ce membre est utilisé lorsque le code de commande est SRB_GET_DEVICE_PROPERTY, SRB_SET_DEVICE_PROPERTY, SRB_GET_STREAM_PROPERTYou SRB_SET_STREAM_PROPERTY.

CommandData.OpenFormat

Pointeur vers la structure KSDATAFORMAT qui spécifie le format.

Ce membre est utilisé lorsque le code de commande est SRB_OPEN_STREAM ou SRB_PROPOSE_DATA_FORMAT.

CommandData.ConfigInfo

Pointeur vers la structure PORT_CONFIGURATION_INFORMATION utilisée pour initialiser l’appareil

Ce membre est utilisé lorsque le code de commande est SRB_INITIALIZE_DEVICE.

CommandData.MasterClockHandle

Handle pour l’objet horloge qui sert maintenant d’horloge maître.

Ce membre est utilisé lorsque le code de commande est SRB_OPEN_MASTER_CLOCK ou SRB_INDICATE_MASTER_CLOCK.

CommandData.DeviceState

Spécifie le nouvel état d’alimentation.

Ce membre est utilisé lorsque le code de commande est SRB_CHANGE_POWER_STATE.

CommandData.IntersectInfo

Pointeur vers une structure STREAM_DATA_INTERSECT_INFO qui décrit les paramètres de cette opération.

Ce membre est utilisé lorsque le code de commande est SRB_GET_DATA_INTERSECTION.

CommandData.MethodInfo

Pointeur vers une mémoire tampon vers laquelle les données de méthode seront lues ou écrites.

CommandData.FilterTypeIndex

Index de type de filtre pour SRB_OPEN_DEVICE_INSTANCE.

CommandData.Idle

Ce membre est défini sur TRUE si aucun handle ouvert n’est conservé sur l’appareil. Ce membre est défini sur FALSE si l’appareil n’est plus inactif (un handle à l’appareil a été ouvert).

Ce membre est utilisé lorsque le code de commande est SRB_NOTIFY_IDLE_STATE.

_CommandData

CommandData est une union de membres fournis pour les données spécifiques au code de commande.

NumberOfBuffers

Si La commande est SRB_READ_DATA ou SRB_WRITE_DATA, cela spécifie le nombre d’entrées dans le tableau de structures KSSTREAM_HEADER qui commencent à l’adresse pointée par CommandData.DataBufferArray. Sinon, ce paramètre n’est pas utilisé.

TimeoutCounter

Nombre de secondes avant l’expiration de cette requête. Le pilote de classe décrémente cette fois par seconde. Si le pilote de classe décrémente TimeoutCounter à zéro avant que le minidriver ne termine cette requête, il appelle la routine StrMiniRequestTimeout du minidriver. Si le minidriver définit cette valeur sur zéro, la requête n’expire pas.

TimeoutOriginal

Le pilote de classe définit cette valeur sur la valeur d’origine de TimeoutCounter lors de la création du SRB.

NextSRB

Pointe vers un autre bloc de demande de flux. Le minidriver peut utiliser ce membre pour mettre en file d’attente les blocs de requête de flux.

Irp

Pointeur vers l’IRP de la requête. La plupart des minidrivers n’ont pas besoin d’utiliser ce membre.

Flags

Spécifie le type de requête. Le pilote de classe et le minidriver peuvent utiliser ce membre pour déterminer le rappel auquel le pilote de classe a passé ce bloc de demande de flux.

Valeur Rappel utilisé
Aucun 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 est défini pour les requêtes spécifiques au flux (qui sont transmises aux routines StrMiniReceiveStreamXxxPacket du minidriver). Le bit SRB_HW_FLAGS_DATA_TRANSFER est défini pour les demandes de transfert de données (qui sont passées au minidriver).

HwInstanceExtension

Pointeur vers l’extension d’instance du minidriver. Le minidriver peut utiliser cette mémoire tampon pour enregistrer des informations privées globales dans cette instance du minidriver. Le minidriver définit la taille de cette mémoire tampon dans la structure HW_INITIALIZATION_DATA qu’il transmet lorsqu’il s’inscrit via StreamClassRegisterMinidriver.

NumberOfBytesToTransfer

Pour une requête SRB_READ_DATA ou SRB_WRITE_DATA, nombre d’octets à transférer.

ActualBytesTransferred

Pour les demandes de contrôle, le nombre d’octets réellement transférés.

ScatterGatherBuffer

Pointe vers un tableau de structures KSSCATTER_GATHER, de la forme :

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

Le tableau décrit une liste de points/regroupements qui peut être utilisée par le minidriver pour effectuer DMA. La mémoire n’a pas besoin d’être sonde, verrouillée, mappée ou vidée. Le pilote de classe de flux effectue ces opérations pour le minidriver.

NumberOfPhysicalPages

Spécifie la taille du tableau passé dans le membre ScatterGatherBuffer.

NumberOfScatterGatherElements

Spécifie le nombre d’éléments physiques pointés par ScatterGatherBuffer.

Reserved[1]

Le champ Réservé[1] est réservé à l’utilisation du système. N’utilisez pas.

Remarques

Le pilote de classe de flux passe des pointeurs vers des structures HW_STREAM_REQUEST_BLOCK aux StrMiniReceiveStreamDataPacket, StrMiniReceiveStreamControlPacketet StrMiniReceiveDevicePacket routines.

Le minidriver possède ce bloc de requête de flux jusqu’à ce que la requête expire ou qu’elle termine la requête. Le minidriver signale au pilote de classe qu’il a terminé la requête en appelant StreamClassDeviceNotification(DeviceRequestComplete, pSrb->HwDeviceExtension, pSRB) pour les requêtes spécifiques à l’appareil ou en appelant StreamClassStreamNotification(StreamRequestComplete, pSrb->StreamObject, pSrb) pour les requêtes spécifiques au flux. (Le minidriver peut également effectuer une requête en appelant StreamClassCompleteRequestAndMarkQueueReady(pSrb). Consultez cette routine pour plus d’informations.)

Si le pilote de classe expire la demande, il appelle la routine StrMiniRequestTime out du minidriver, qui a la responsabilité de terminer le traitement de la demande. Si le minidriver met en file d’attente une demande de traitement ultérieur, il doit définir l'TimeoutCounter membre sur zéro, ce qui empêchera le pilote de classe d’expirer la requête. Une fois que le minidriver est prêt à reprendre le traitement de la demande, il doit réinitialiser le membre TimeoutCounter à la valeur de TimeoutOriginal.

Exigences

Exigence Valeur
d’en-tête strmini.h (include Strmini.h)