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