Méthode IWDFUsbTargetPipe2 ::ConfigureContinuousReader (wudfusb.h)

Article
03/01/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 méthode ConfigureContinuousReader configure l’infrastructure pour lire en continu à partir d’un canal USB.

Syntaxe

HRESULT ConfigureContinuousReader(
  [in]           SIZE_T                                              TransferLength,
  [in]           SIZE_T                                              HeaderLength,
  [in]           SIZE_T                                              TrailerLength,
  [in]           UCHAR                                               NumPendingReads,
  [in, optional] IUnknown                                            *pMemoryCleanupCallbackInterface,
  [in]           IUsbTargetPipeContinuousReaderCallbackReadComplete  *pOnCompletion,
  [in, optional] PVOID                                               pCompletionContext,
  [in, optional] IUsbTargetPipeContinuousReaderCallbackReadersFailed *pOnFailure
);

Paramètres

[in] TransferLength

Longueur maximale, en octets, des données pouvant être reçues de l’appareil.

[in] HeaderLength

Décalage, en octets, dans la mémoire tampon qui reçoit les données de l’appareil. L’infrastructure stocke les données de l’appareil dans une mémoire tampon de lecture, en commençant par la valeur de décalage. En d’autres termes, cet espace précède l’espace de taille TransferLength dans lequel l’infrastructure stocke les données de l’appareil.

[in] TrailerLength

Longueur, en octets, d’un espace tampon de fin. Cet espace suit l’espace de taille TransferLength dans lequel l’infrastructure stocke les données de l’appareil.

[in] NumPendingReads

Nombre de demandes de lecture que l’infrastructure met en file d’attente pour recevoir des données de la cible d’E/S. Si cette valeur est égale à zéro, l’infrastructure utilise un nombre par défaut de demandes de lecture. Si la valeur spécifiée est supérieure à la valeur maximale autorisée, l’infrastructure utilise la valeur maximale autorisée. Pour plus d’informations sur le paramètre NumPendingReads , consultez la section Remarques suivante.

[in, optional] pMemoryCleanupCallbackInterface

Pointeur vers une interface IUnkown fournie par le pilote que le framework utilise pour accéder à une fonction de rappel IObjectCleanup ::OnCleanup facultative. L’infrastructure appelle la fonction de rappel lorsqu’elle libère la mémoire tampon de lecture qu’elle crée pour gérer l’opération de lecture continue. Ce paramètre est facultatif et peut être NULL.

[in] pOnCompletion

Pointeur vers une interface IUsbTargetPipeContinuousReaderCallbackReadComplete fournie par le pilote qui fournit une fonction de rappel OnReaderCompletion .

[in, optional] pCompletionContext

Pointeur non typé vers les informations de contexte définies par le pilote que l’infrastructure transmet à la fonction de rappel IUsbTargetPipeContinuousReaderCallbackReadComplete ::OnReaderCompletion du pilote.

[in, optional] pOnFailure

Pointeur vers une interface IUsbTargetPipeContinuousReaderCallbackReaderFailed fournie par le pilote qui fournit une fonction de rappel OnReaderFailure .

Valeur retournée

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

Code de retour	Description
HRESULT_FROM_NT (STATUS_INVALID_DEVICE_STATE)	Le pilote a déjà configuré un lecteur continu pour le canal USB. Le canal USB n’est pas configuré pour les transferts d’entrée en bloc ou d’interruption.
E_OUTOFMEMORY	La tentative de l’infrastructure d’allouer une mémoire tampon a échoué.
ERROR_ARITHMETIC_OVERFLOW	Le paramètre TransferLength, HeaderLength ou TrailerLength a spécifié une taille trop grande ou non valide.

Cette méthode peut retourner l’une des autres valeurs que Winerror.h contient.

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é ConfigureContinuousReader pour configurer un lecteur continu, votre pilote doit appeler IWDFIoTargetStateManagement ::Start pour démarrer le lecteur. Pour arrêter le lecteur, le pilote doit appeler IWDFIoTargetStateManagement ::Stop.

En règle générale, un pilote appelle ConfigureContinuousReader à partir de sa fonction de rappel IPnpCallbackHardware ::OnPrepareHardware . Le pilote doit appeler IWDFIoTargetStateManagement ::Démarrer à partir de sa fonction de rappel IPnpCallback ::OnD0Entry et doit appeler IWDFIoTargetStateManagement ::Stop à partir de sa fonction de rappel IPnpCallback ::OnD0Exit .

Chaque fois que la cible d’E/S du canal termine correctement une demande de lecture, l’infrastructure appelle la fonction de rappel IUsbTargetPipeContinuousReaderCallbackReadComplete ::OnReaderCompletion du pilote. Si la cible d’E/S signale un échec lors du traitement d’une demande, l’infrastructure appelle la fonction de rappel IUsbTargetPipeContinuousReaderCallbackReadersFailed ::OnReaderFailure du pilote une fois que toutes les demandes de lecture sont terminées. (Par conséquent, la fonction de rappel OnReaderCompletion n’est pas appelée pendant l’exécution de la fonction de rappel OnReaderFailure .)

Utilisez les instructions suivantes pour choisir une valeur pour le paramètre NumPendingReads :

Définissez NumPendingReads sur zéro si vous souhaitez que votre pilote utilise la valeur par défaut de l’infrastructure.
La valeur par défaut est supérieure à un et fournit des performances relativement bonnes pour de nombreux appareils sur de nombreuses configurations de processeur.
Définissez NumPendingReads sur un si il est important que votre pilote reçoive des mémoires tampons de données dans l’ordre exact dans lequel l’appareil fournit les données.
Si l’infrastructure met en file d’attente plusieurs demandes de lecture, le pilote peut ne pas recevoir les mémoires tampons de données dans l’ordre dans lequel l’appareil fournit les données.
Définissez NumPendingReads sur un nombre qui répond aux exigences de performances de votre appareil, en fonction de mesures de performances approfondies.
Tout d’abord, testez votre appareil avec la valeur par défaut (0) pour NumPendingReads. Vos tests doivent inclure différentes configurations matérielles, notamment différents types et nombres de processeurs, ainsi que différents contrôleurs hôtes USB et configurations USB. Vous pouvez ensuite tester des valeurs plus élevées à l’aide des mêmes tests. Un pilote qui peut nécessiter une valeur plus élevée est un pilote pour un appareil dont le taux d’interruption est élevé, où les données peuvent être perdues si les interruptions ne sont pas rapidement mises en service.

Une valeur NumPendingReads trop grande peut ralentir les performances d’un système. Vous devez utiliser la valeur la plus basse qui répond à vos exigences de performances. En règle générale, les valeurs supérieures à trois ou quatre n’améliorent pas le débit des données. Toutefois, des valeurs plus élevées peuvent réduire la latence, ou le risque de données manquantes, sur un canal à haute fréquence.

Une fois qu’un pilote a appelé ConfigureContinuousReader, le pilote ne peut pas utiliser IWDFIoRequest ::Send pour envoyer des demandes d’E/S au canal, sauf si la fonction de rappel IUsbTargetPipeContinuousReaderCallbackReaderFailed ::OnReaderFailure est appelée et retourne FALSE.

Pour plus d’informations sur la méthode ConfigureContinuousReader et les cibles d’E/S USB, consultez Lecture à partir d’un canal UMDF-USB.

Exemples

L’exemple de code suivant configure un lecteur continu. Dans cet exemple, la taille maximale de la mémoire tampon correspond à la taille d’une mémoire tampon définie par le pilote. Les décalages de mémoire tampon d’en-tête et de bande-annonce sont définis sur zéro, et le nombre d’opérations de lecture en attente est défini sur deux. L’exemple utilise le pointeur d’interface du canal cible pour le paramètre pCompletionContext , de sorte que la fonction de rappel OnReaderCompletion peut déterminer le canal sur lequel l’opération de lecture a été effectuée.

HRESULT hr, hrQI;
IUsbTargetPipeContinuousReaderCallbackReadComplete *pOnCompletionCallback = NULL;
IUsbTargetPipeContinuousReaderCallbackReadersFailed *pOnFailureCallback= NULL;
IWDFUsbTargetPipe2 * pIUsbInterruptPipe2;

//
// Obtain interfaces.
//
hrQI = this->QueryInterface(IID_PPV_ARGS(&pOnCompletionCallback));
if (!SUCCEEDED(hrQI)) goto Error;
hrQI = this->QueryInterface(IID_PPV_ARGS(&pOnFailureCallback));
if (!SUCCEEDED(hrQI)) goto Error;
hrQI = m_pIUsbInterruptPipe->QueryInterface(IID_PPV_ARGS(&pIUsbInterruptPipe2));
if (!SUCCEEDED(hrQI)) goto Error;

//
// Configure the reader.
//
hr = pIUsbInterruptPipe2->ConfigureContinuousReader(
                                                    sizeof(m_MyBuffer), 
                                                    0,
                                                    0,
                                                    2, 
                                                    NULL,
                                                    pOnCompletionCallback,
                                                    m_pIUsbTargetPipe,
                                                    pOnFailureCallback
                                                    );
...

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)
DLL	WUDFx.dll