Méthode IUsbTargetPipeContinuousReaderCallbackReadComplete ::OnReaderCompletion (wudfusb.h)

Article
03/05/2024

[Avertissement : UMDF 2 est la dernière version d’UMDF et remplace UMDF 1. Tous les nouveaux pilotes UMDF doivent être écrits à l’aide d’UMDF 2. Aucune nouvelle fonctionnalité n’est ajoutée à UMDF 1 et la prise en charge d’UMDF 1 est limitée sur les versions plus récentes de Windows 10. Les pilotes Windows universels doivent utiliser UMDF 2. Pour plus d’informations, consultez Prise en main avec UMDF.]

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

Syntaxe

void OnReaderCompletion(
  [in] IWDFUsbTargetPipe *pPipe,
  [in] IWDFMemory        *pMemory,
  [in] SIZE_T            NumBytesTransferred,
  [in] PVOID             Context
);

Paramètres

[in] pPipe

Pointeur vers l’interface IWDFUsbTargetPipe pour le canal USB sur lequel le pilote a activé un lecteur continu.

[in] pMemory

Pointeur vers l’interface IWDFMemory pour une mémoire tampon de lecture qui contient des données lues à partir du canal USB.

[in] NumBytesTransferred

Nombre d’octets que contient la mémoire tampon de lecture.

[in] Context

Pointeur vers les informations de contexte fournies par le pilote lorsque le pilote a précédemment appelé IWDFUsbTargetPipe2 ::ConfigureContinuousReader.

Valeur de retour

None

Remarques

Pour inscrire une fonction de rappel IUsbTargetPipeContinuousReaderCallbackReadComplete ::OnReaderCompletion , votre pilote doit fournir un pointeur vers l’interface IUsbTargetPipeContinuousReaderCallbackReadComplete du pilote lorsqu’il appelle IWDFUsbTargetPipe2 ::ConfigureContinuousReader.

Si un pilote a créé un lecteur continu pour un canal USB, l’infrastructure appelle la fonction de rappel OnReaderCompletion du pilote chaque fois que la cible d’E/S du pilote termine correctement une demande de lecture. Si la cible d’E/S ne termine pas correctement une demande, l’infrastructure appelle la fonction de rappel IUsbTargetPipeContinuousReaderCallbackReaderFailed ::OnReaderFailure du pilote.

Pour accéder à la mémoire tampon qui contient des données lues à partir de l’appareil, le pilote peut appeler IWDFMemory ::GetDataBuffer. Le framework écrit les données dans la mémoire tampon, après l’en-tête défini par le paramètre HeaderLength de IWDFUsbTargetPipe2 ::ConfigureContinuousReader. Notez que le pointeur renvoyé par IWDFMemory ::GetDataBuffer pointe vers le début de l’en-tête, mais que le paramètre NumBytesTransferred de la fonction de rappel OnReaderCompletion 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 après le retour de la fonction de rappel OnReaderCompletion . 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 pointeur d’interface de l’objet mémoire 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 appeler la méthode IWDFMemory ::AddRef de la mémoire tampon. Par la suite, le pilote doit appeler la méthode IWDFMemory ::Release de la mémoire tampon afin que l’infrastructure puisse supprimer l’objet.

L’infrastructure synchronise les appels aux fonctions de rappel OnReaderCompletion et IUsbTargetPipeContinuousReaderCallbackReaderFailed ::OnReaderFailure 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 OnReaderCompletion et OnReaderFailure , les fonctions de rappel multiples peuvent s’exécuter simultanément.
Si le pilote a spécifié la valeur NumPendingReads par défaut lorsqu’il appelle IWDFUsbTargetPipe2 ::ConfigureContinuousReader (ou s’il spécifie une valeur NumPendingReads supérieure à 1), et si une demande de lecture se termine pendant l’exécution de la fonction de rappel OnReaderCompletion , l’infrastructure peut appeler à nouveau la fonction de rappel OnReaderCompletion avant que la fonction de rappel ne retourne.
L’infrastructure ne synchronise pas ces fonctions de rappel avec d’autres fonctions de rappel.

Lorsque votre pilote appelle IWDFUsbTargetPipe2 ::ConfigureContinuousReader, il peut spécifier une fonction de rappel IObjectCleanup ::OnCleanup . L’infrastructure appelle cette fonction de rappel lorsqu’elle tente de supprimer l’objet mémoire, une fois que la fonction de rappel OnReaderCompletion est retournée.

Pour plus d’informations sur la fonction de rappel OnReaderCompletion et les cibles d’E/S USB, consultez Gestion d’une cible d’E/S USB.

Configuration requise

Condition requise	Valeur
Fin de la prise en charge	Non disponible dans UMDF 2.0 et versions ultérieures.
Plateforme cible	Desktop (Expérience utilisateur)
Version UMDF minimale	1,9
En-tête	wudfusb.h (inclure Wudfusb.h)

Voir aussi

IUsbTargetPipeContinuousReaderCallbackReadComplete

IUsbTargetPipeContinuousReaderCallbackReaderFailed ::OnReaderFailure

Partager via