IUsbTargetPipeContinuousReaderCallbackReadComplete ::OnReaderCompletion, méthode (wudfusb.h)

Article
02/07/2025

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

La fonction de rappel d’événement OnReaderCompletion d’un pilote informe le pilote qu’un lecteur continu a correctement effectué 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 que le pilote a fourni lorsqu’il a précédemment appelé IWDFUsbTargetPipe2 ::ConfigureContinuousReader.

Valeur de retour

Aucun

Remarques

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

Si un pilote a créé un lecteur continu pour un canal USB, l’infrastructure appelle le OnReaderCompletion du pilote fonction de rappel 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 requête, l’infrastructure appelle la fonction de rappel IUsbTargetPipeContinuousReaderCallbackReaderFailed ::OnReaderFailure fonction de rappel.

Pour accéder à la mémoire tampon qui contient des données lues à partir de l’appareil, le pilote peut appeler IWDFMemory ::GetDataBuffer. L’infrastructure é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 qui IWDFMemory ::GetDataBuffer renvoie des points au début de l’en-tête, mais le OnReaderCompletion paramètre fonction de rappel NumBytesTransferred 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 souhaiterez peut-être que l’objet mémoire reste valide une fois la fonction de rappel retournée. Par exemple, vous souhaiterez peut-être que votre pilote stocke le pointeur d’interface de l’objet mémoire dans l’espace de contexte de l’objet de canal d’infrastructure afin que le pilote puisse traiter le contenu de l’objet mémoire une fois la fonction de rappel retournée. 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 OnReaderCompletion et IUsbTargetPipeContinuousReaderCallbackReadersFailed ::OnReaderFailure fonctions de rappel conformément aux 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 OnReaderCompletion et fonctions de rappel OnReaderFailure, les fonctions de rappel multiples peuvent s’exécuter simultanément.
Si le pilote a spécifié la valeur par défaut NumPendingReads lorsqu’il appelle IWDFUsbTargetPipe2 ::ConfigureContinuousReader (ou s’il spécifie une valeur NumPendingReads supérieure à 1), et si une demande de lecture est terminée pendant l’exécution de la fonction de rappel OnReaderCompletion, l’infrastructure peut appeler à nouveau la fonction de rappel OnReaderCompletion avant le retour de la fonction de rappel.
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 un IObjectCleanup ::OnCleanup fonction de rappel. L’infrastructure appelle cette fonction de rappel lorsqu’elle tente de supprimer l’objet mémoire, après la OnReaderCompletion fonction de rappel retourne.

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

Exigences

Exigence	Valeur
fin du support	Indisponible dans UMDF 2.0 et versions ultérieures.
plateforme cible	Bureau
version minimale de UMDF	1.9
d’en-tête	wudfusb.h (include Wudfusb.h)

Voir aussi

IUsbTargetPipeContinuousReaderCallbackReadComplete

IUsbTargetPipeContinuousReaderCallbackReadersFailed ::OnReaderFailure

Partager via