structure HW_STREAM_REQUEST_BLOCK (strmini.h)

Le pilote de classe de flux utilise la structure HW_STREAM_REQUEST_BLOCK pour transmettre des informations à et à partir du minidriver, à l’aide des 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 transmet SRB_XXX codes de commande aux rappels minidriver.

Status

Lorsque le minidriver termine une demande de flux, il remplit ce membre avec le code status de la demande. Consultez la documentation relative à la routine de requêteStrMiniXxx appropriée pour connaître les codes status les mini-drives sont censés utiliser.

StreamObject

Pour les requêtes orientées flux, le pilote de classe définit ce paramètre pour qu’il pointe 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 de l’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 passe lorsqu’il s’inscrit lui-même via StreamClassRegisterMinidriver. Le pilote de classe transmet également des pointeurs vers cette mémoire tampon dans le membre HwDeviceExtension du HW_STREAM_OBJECT, HW_TIME_CONTEXT et PORT_CONFIGURATION_INFORMATION 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 demande de flux. Cette mémoire tampon est libérée une fois que le minidriver a terminé 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 dans 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 le membre StreamDescriptorSize 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. Pour plus d’informations, consultez KSPROPERTY_CONNECTION_STATE .

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 propriété.

Ce membre est utilisé lorsque le code de commande est SRB_GET_DEVICE_PROPERTY, SRB_SET_DEVICE_PROPERTY, SRB_GET_STREAM_PROPERTY ou 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 d’horloge qui sert désormais d’horloge master.

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 à partir de 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 sur l’appareil ne reste. Ce membre a la valeur FALSE si l’appareil n’est plus inactif (un handle de 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 Command est SRB_READ_DATA ou SRB_WRITE_DATA, cela spécifie le nombre d’entrées dans le tableau de structures KSSTREAM_HEADER qui commence à 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 cela une fois par seconde. Si le pilote de classe décrémente TimeoutCounter à zéro avant que le minidriver ne termine cette demande, il appelle la routine StrMiniRequestTimeout du minidriver. Si le minidriver définit ce paramètre sur zéro, la demande 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 demande de flux.

Irp

Pointeur vers l’IRP pour la demande. 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 à quel rappel le pilote de classe a passé ce bloc de demande de flux.

SRB_HW_FLAGS_STREAM_REQUEST bit est défini pour les requêtes spécifiques au flux (qui sont transmises aux routines de paquets StrMiniReceiveStreamXxx du minidriver). Le SRB_HW_FLAGS_DATA_TRANSFER bit est défini pour les demandes de transfert de données (qui sont passées au minidriver).

HwInstanceExtension

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

NumberOfBytesToTransfer

Pour une requête SRB_READ_DATA ou SRB_WRITE_DATA, le 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/regroupement qui peut être utilisée par le minidriver pour effectuer DMA. La mémoire n’a pas besoin d’être sondée, 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 transmis 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. Ne pas utiliser.

Remarques

Le pilote de classe de flux transmet des pointeurs vers HW_STREAM_REQUEST_BLOCK structures vers les routines StrMiniReceiveStreamDataPacket, StrMiniReceiveStreamControlPacket et StrMiniReceiveDevicePacket du minidriver.

Le minidriver possède ce bloc de demande de flux jusqu’à ce que la requête expire ou qu’il termine la demande. Le minidriver signale au pilote de classe qu’il a terminé la demande 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 demande en appelant StreamClassCompleteRequestAndMarkQueueReady(pSrb). Pour plus d’informations, consultez cette routine.)

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

Configuration requise