WdfUsbTargetPipeConfigContinuousReader, fonction (wdfusb.h)

Article
08/08/2023

[S’applique à KMDF et UMDF]

La méthode WdfUsbTargetPipeConfigContinuousReader configure l’infrastructure pour lire en continu à partir d’un canal USB spécifié.

Syntaxe

NTSTATUS WdfUsbTargetPipeConfigContinuousReader(
  [in] WDFUSBPIPE                        Pipe,
  [in] PWDF_USB_CONTINUOUS_READER_CONFIG Config
);

Paramètres

[in] Pipe

Handle d’un objet de canal d’infrastructure obtenu en appelant WdfUsbInterfaceGetConfiguredPipe.

[in] Config

Pointeur vers une structure de WDF_USB_CONTINUOUS_READER_CONFIG allouée par l’appelant.

Valeur retournée

WdfUsbTargetPipeConfigContinuousReader retourne STATUS_SUCCESS si l’opération réussit. Sinon, cette méthode peut retourner l’une des valeurs suivantes :

Code de retour	Description
STATUS_INFO_LENGTH_MISMATCH	La taille de la structure WDF_USB_CONTINUOUS_READER_CONFIG spécifiée par le paramètre Config était incorrecte.
STATUS_INVALID_PARAMETER	Un paramètre non valide a été détecté.
STATUS_INSUFFICIENT_RESOURCES	La mémoire disponible était insuffisante.
STATUS_INVALID_DEVICE_REQUEST	Le type du canal n’était pas valide.
STATUS_INTEGER_OVERFLOW	Le membre HeaderLength, TransferLength ou TrailerLength de la structure WDF_USB_CONTINUOUS_READER_CONFIG que le paramètre Config a spécifié une taille trop grande ou non valide.
STATUS_INVALID_BUFFER_SIZE	La taille de la mémoire tampon de lecture n’était pas un multiple de la taille maximale du paquet du canal.

Pour obtenir la liste des autres valeurs de retour que la méthode WdfUsbTargetPipeConfigContinuousReader peut retourner, consultez Erreurs de création d’objet Framework.

Cette méthode peut également retourner d’autres valeurs NTSTATUS.

Un bogue case activée se produit si le pilote fournit un handle d’objet non valide.

Remarques

Vous pouvez configurer un lecteur continu pour un canal en bloc ou un canal d’interruption. Le canal doit avoir un point de terminaison d’entrée.

Après avoir appelé WdfUsbTargetPipeConfigContinuousReader pour configurer un lecteur continu, votre pilote doit appeler WdfIoTargetStart pour démarrer le lecteur. Pour arrêter le lecteur, le pilote doit appeler WdfIoTargetStop.

En règle générale, un pilote appelle WdfUsbTargetPipeConfigContinuousReader à partir de sa fonction de rappel EvtDevicePrepareHardware . Le pilote doit appeler WdfIoTargetStart à partir de sa fonction de rappel EvtDeviceD0Entry et doit appeler WdfIoTargetStop à partir de sa fonction de rappel EvtDeviceD0Exit .

Chaque fois que la cible d’E/S du canal termine correctement une demande de lecture, l’infrastructure appelle la fonction de rappel EvtUsbTargetPipeReadComplete du pilote. Si la cible d’E/S signale un échec lors du traitement d’une demande, l’infrastructure appelle la fonction de rappel EvtUsbTargetPipeReadersFailed du pilote une fois que toutes les demandes de lecture ont été effectuées. (Par conséquent, la fonction de rappel EvtUsbTargetPipeReadComplete n’est pas appelée pendant l’exécution de la fonction de rappel EvtUsbTargetPipeReadersFailed ).

Si vous ne fournissez pas le rappel facultatif EvtUsbTargetPipeReadersFailed , le framework répond à une tentative de lecture ayant échoué en envoyant une autre demande de lecture. Par conséquent, si le bus est dans un état où il n’accepte pas de lectures, l’infrastructure envoie continuellement de nouvelles demandes pour récupérer après un échec de lecture.

Une fois qu’un pilote a appelé WdfUsbTargetPipeConfigContinuousReader, le pilote ne peut pas utiliser WdfUsbTargetPipeReadSynchronously ou WdfRequestSend pour envoyer des demandes d’E/S au canal, sauf si le lecteur continu a été arrêté. Pour arrêter le lecteur, le pilote peut appeler WdfIoTargetStop ou retourner FALSE à partir de sa fonction de rappel EvtUsbTargetPipeReadersFailed . Si le pilote appelle WdfUsbTargetPipeReadSynchronously lorsque le lecteur est arrêté, il doit définir l’indicateur WDF_REQUEST_SEND_OPTION_IGNORE_TARGET_STATE dans le membre Flags du paramètre RequestOptions . Dans le cas contraire, la demande sera suspendu jusqu’à ce que la cible soit redémarrée.

L’infrastructure définit l’indicateur USBD_SHORT_TRANSFER_OK dans son URB interne. La définition de cet indicateur permet au dernier paquet d’un transfert de données d’être inférieur à la taille maximale du paquet.

Pour plus d’informations sur la méthode WdfUsbTargetPipeConfigContinuousReader et les cibles d’E/S USB, consultez Lecture à partir d’un canal.

Exemples

L’exemple de code suivant initialise une structure WDF_USB_CONTINUOUS_READER_CONFIG et appelle WdfUsbTargetPipeConfigContinuousReader.

WDF_USB_CONTINUOUS_READER_CONFIG  contReaderConfig;
NTSTATUS  status;

WDF_USB_CONTINUOUS_READER_CONFIG_INIT(
                                      &contReaderConfig,
                                      OsrFxEvtUsbInterruptPipeReadComplete,
                                      DeviceContext,
                                      sizeof(UCHAR)
                                      );
status = WdfUsbTargetPipeConfigContinuousReader(
                                      Pipe,
                                      &contReaderConfig
                                      );

Configuration requise

Condition requise	Valeur
Plateforme cible	Universal
Version KMDF minimale	1.0
Version UMDF minimale	2.0
En-tête	wdfusb.h (inclure Wdfusb.h)
Bibliothèque	Wdf01000.sys (KMDF) ; WUDFx02000.dll (UMDF)
IRQL	<=DISPATCH_LEVEL
Règles de conformité DDI	DriverCreate(kmdf),FailD0EntryIoTargetState(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf), UsbContReader(kmdf), UsbKmdfIrql(kmdf), UsbKmdfIrql2(kmdf), UsbKmdfIrqlExplicit(kmdf)