WdfUsbTargetPipeConfigContinuousReader, fonction (wdfusb.h)

Article
02/07/2025

[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 vers un objet de canal d’infrastructure obtenu en appelant WdfUsbInterfaceGetConfiguredPipe.

[in] Config

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

Valeur de retour

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

Retourner le code	Description
STATUS_INFO_LENGTH_MISMATCH	La taille de la structure WDF_USB_CONTINUOUS_READER_CONFIG spécifiée par le paramètre Config spécifié était incorrecte.
STATUS_INVALID_PARAMETER	Un paramètre non valide a été détecté.
STATUS_INSUFFICIENT_RESOURCES	Mémoire insuffisante disponible.
STATUS_INVALID_DEVICE_REQUEST	Le type du canal n’était pas valide.
STATUS_INTEGER_OVERFLOW	HeaderLength, TransferLengthou membre 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 Framework Object Creation Errors.

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

Une vérification de bogue 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 son EvtDevicePrepareHardware fonction de rappel. Le pilote doit appeler WdfIoTargetStart à partir de sa fonction de rappel EvtDeviceD0Ent ry 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 EvtUsbTargetPipeReadComplete du pilote fonction de rappel. Si la cible d’E/S signale un échec lors du traitement d’une demande, l’infrastructure appelle la EvtUsbTargetPipeReadersFailed fonction de rappel une fois toutes les demandes de lecture terminées. (Par conséquent, la fonction de rappel EvtUsbTargetPipeReadComplete ne sera pas appelée pendant l’exécution de la fonction de rappel evtUsbTargetPipeReadersFailed EvtUsbTargetPipeReadersFailed fonction de rappel).

Si vous ne fournissez pas le rappel facultatif EvtUsbTargetPipeReadersFailed, l’infrastructure 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 requêtes pour récupérer à partir d’une lecture ayant échoué.

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 faux à partir de sa fonction de rappel EvtUsbTargetPipeReadersFailed. Si le pilote appelle WdfUsbTargetPipeReadSynchronously pendant que le lecteur est arrêté, il doit définir l’indicateur WDF_REQUEST_SEND_OPTION_IGNORE_TARGET_STATE dans les indicateurs membre du paramètre RequestOptions. Sinon, la requête est bloquée jusqu’à ce que la cible soit redémarrée.

Le framework 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 des paquets.

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

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
                                      );

Exigences

Exigence	Valeur
plateforme cible	Universel
version minimale de KMDF	1.0
version minimale de UMDF	2.0
d’en-tête	wdfusb.h (include 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)