EVT_WDF_USB_READER_COMPLETION_ROUTINE fonction de rappel (wdfusb.h)

[S’applique à KMDF et UMDF]

La fonction de rappel d’événement EvtUsbTargetPipeReadComplete d’un pilote informe le pilote qu’un lecteur continu a réussi une demande de lecture.

Syntaxe

EVT_WDF_USB_READER_COMPLETION_ROUTINE EvtWdfUsbReaderCompletionRoutine;

void EvtWdfUsbReaderCompletionRoutine(
  [in] WDFUSBPIPE Pipe,
  [in] WDFMEMORY Buffer,
  [in] size_t NumBytesTransferred,
  [in] WDFCONTEXT Context
)
{...}

Paramètres

[in] Pipe

Handle vers un objet de canal d’infrastructure.

[in] Buffer

Handle vers un objet de mémoire d’infrastructure qui représente une mémoire tampon qui contient des données de l’appareil.

[in] NumBytesTransferred

Nombre d’octets de données qui se trouvent dans la mémoire tampon de lecture.

[in] Context

Informations de contexte définies par le pilote que le pilote a spécifiées dans le membre EvtUsbTargetPipeReadCompleteContext de la structure WDF_USB_CONTINUOUS_READER_CONFIG du canal.

Valeur de retour

None

Remarques

Pour inscrire une fonction de rappel EvtUsbTargetPipeReadComplete , le pilote doit placer l’adresse de la fonction dans une structure WDF_USB_CONTINUOUS_READER_CONFIG .

Si un pilote a créé un lecteur continu pour un canal USB, le framework appelle la fonction de rappel EvtUsbTargetPipeReadComplete du pilote chaque fois que la cible d’E/S du pilote termine correctement une demande de lecture. La fonction de rappel est appelée au niveau de l’IRQL au niveau duquel la cible d’E/S a effectué la demande de lecture, qui est généralement IRQL = DISPATCH_LEVEL, mais pas supérieure à DISPATCH_LEVEL. (Si la cible d’E/S ne termine pas correctement une demande, l’infrastructure appelle la fonction de rappel EvtUsbTargetPipeReadersFailed du pilote.)

Pour accéder à la mémoire tampon qui contient les données lues à partir de l’appareil, le pilote peut appeler WdfMemoryGetBuffer. Le framework écrit les données dans la mémoire tampon, après l’en-tête défini par le membre HeaderLength de la structure WDF_USB_CONTINUOUS_READER_CONFIG . Notez que le pointeur que WdfMemoryGetBuffer retourne pointe vers le début de l’en-tête, mais que le paramètre NumBytesTransferred de la fonction de rappel EvtUsbTargetPipeReadComplete n’inclut pas la longueur de l’en-tête.

Par défaut, l’infrastructure supprime l’objet mémoire de la mémoire tampon une fois la fonction de rappel EvtUsbTargetPipeReadComplete retournée. Toutefois, vous pouvez souhaiter que l’objet mémoire reste valide après le retour de la fonction de rappel. Par exemple, vous pouvez souhaiter que votre pilote stocke le handle d’objet dans l’espace contextuel de l’objet de canal d’infrastructure afin que le pilote puisse traiter le contenu de l’objet mémoire après le retour de la fonction de rappel. Pour prolonger la durée de vie de l’objet mémoire, la fonction de rappel doit passer le handle de l’objet mémoire à WdfObjectReference. Par la suite, le pilote doit appeler WdfObjectDereference pour que l’infrastructure puisse supprimer l’objet .

L’infrastructure synchronise les appels aux fonctions de rappel EvtUsbTargetPipeReadComplete et EvtUsbTargetPipeReadersFailed selon les règles suivantes :

• Ces fonctions de rappel ne s’exécutent pas simultanément pour un canal USB individuel.
• Si le pilote crée plusieurs lecteurs continus pour plusieurs canaux USB, avec plusieurs fonctions de rappel EvtUsbTargetPipeReadComplete et EvtUsbTargetPipeReadersFailed , les fonctions de rappel multiples peuvent s’exécuter simultanément.
• Si le pilote a spécifié la valeur NumPendingReads par défaut ou une valeur supérieure à 1, et si une demande de lecture se termine pendant que la fonction de rappel EvtUsbTargetPipeReadComplete est en cours d’exécution, l’infrastructure peut appeler à nouveau la fonction de rappel EvtUsbTargetPipeReadComplete avant que la fonction de rappel ne retourne.
• L’infrastructure ne synchronise pas ces fonctions de rappel avec d’autres fonctions de rappel.

Dans le membre BufferAttributes de la structure WDF_USB_CONTINUOUS_READER_CONFIG , votre pilote peut spécifier les fonctions de rappel EvtCleanupCallback et EvtDestroyCallback pour l’objet mémoire. Si vous spécifiez une fonction de rappel EvtCleanupCallback , l’infrastructure appelle cette fonction de rappel lorsqu’elle tente de supprimer l’objet mémoire, une fois la fonction de rappel EvtUsbTargetPipeReadComplete retournée. Si la fonction de rappel EvtUsbTargetPipeReadComplete a appelé WdfObjectReference, la fonction de rappel EvtCleanupCallback (si elle est fournie) ne doit pas appeler WdfObjectDereference.

Le pilote doit appeler WdfObjectDereference lorsqu’il a fini d’utiliser l’objet mémoire. L’infrastructure peut ensuite appeler la fonction de rappel EvtDestroyCallback du pilote (si elle est fournie) et supprimer l’objet mémoire.

Pour plus d’informations sur la fonction de rappel EvtUsbTargetPipeReadComplete et les cibles d’E/S USB, consultez Cibles d’E/S USB.

Configuration requise

Condition requise	Valeur
Plateforme cible	Universal
Version KMDF minimale	1.0
Version UMDF minimale	2.0
En-tête	wdfusb.h (inclure Wdf.h)
IRQL	<=DISPATCH_LEVEL (voir la section Notes.)

Voir aussi

EvtUsbTargetPipeReadersFailed

WDF_USB_CONTINUOUS_READER_CONFIG

WdfMemoryGetBuffer