WinUsb_ReadPipe, fonction (winusb.h)
La fonction WinUsb_ReadPipe lit les données du canal spécifié.
Syntaxe
BOOL WinUsb_ReadPipe(
[in] WINUSB_INTERFACE_HANDLE InterfaceHandle,
[in] UCHAR PipeID,
[out] PUCHAR Buffer,
[in] ULONG BufferLength,
[out, optional] PULONG LengthTransferred,
[in, optional] LPOVERLAPPED Overlapped
);
Paramètres
[in] InterfaceHandle
Handle opaque pour l’interface qui contient le point de terminaison auquel le canal est associé.
Pour lire les données du canal associé à un point de terminaison dans la première interface, utilisez le handle retourné par WinUsb_Initialize. Pour toutes les autres interfaces, utilisez le handle de l’interface cible, récupéré par WinUsb_GetAssociatedInterface.
[in] PipeID
PipeID correspond au champ bEndpointAddress dans le descripteur de point de terminaison. Pour plus d’informations sur la disposition de ce champ, voir le tableau 9-13 de la section « Universal Serial Bus Specification Revision 2.0 » sur USB Technology. Dans le champ bEndpointAddress , Bit 7 indique la direction du point de terminaison : 0 pour OUT ; 1 pour IN.
[out] Buffer
Mémoire tampon allouée à l’appelant qui reçoit les données lues.
[in] BufferLength
Nombre maximal d'octets à lire. Ce nombre doit être inférieur ou égal à la taille, en octets, de Buffer.
[out, optional] LengthTransferred
Pointeur vers une variable ULONG qui reçoit le nombre réel d’octets qui ont été copiés dans Buffer. Pour plus d'informations, consultez la section Notes.
[in, optional] Overlapped
Pointeur facultatif vers une structure CHEVAUCHEMENT UTILISÉE pour les opérations asynchrones. Si ce paramètre est spécifié, WinUsb_ReadPipe retourne immédiatement au lieu d’attendre de façon synchrone que l’opération se termine avant de revenir. Un événement est signalé lorsque l’opération est terminée.
Valeur retournée
WinUsb_ReadPipe retourne TRUE si l’opération réussit. Sinon, cette fonction retourne FALSE et l’appelant peut récupérer l’erreur journalisée en appelant GetLastError.
GetLastError peut retourner le code d’erreur suivant.
| Code de retour | Description |
|---|---|
|
L’appelant a passé la valeur NULL dans le paramètre InterfaceHandle . |
|
Une opération d’E/S qui se chevauche est en cours, mais n’est pas terminée. Si l’opération qui se chevauche ne peut pas être effectuée immédiatement, la fonction retourne FALSE et la fonction GetLastError retourne ERROR_IO_PENDING, indiquant que l’opération s’exécute en arrière-plan. Appelez WinUsb_GetOverlappedResult pour case activée la réussite ou l’échec de l’opération. |
|
La mémoire est insuffisante pour effectuer l’opération. |
|
L’opération de lecture lancée par WinUsb_ReadPipe dans la pile USB a expiré avant la fin de l’opération. |
Remarques
Si les données retournées par l’appareil sont supérieures à une longueur de transfert maximale, WinUSB divise la requête en demandes plus petites de la longueur maximale de transfert et les envoie en série. Si la longueur de transfert n’est pas un multiple de la taille maximale du paquet du point de terminaison (récupérable via le membre MaximumPacketSize de la structure WINUSB_PIPE_INFORMATION), WinUSB augmente la taille du transfert au multiple suivant de MaximumPacketSize.
La taille du paquet USB n’est pas prise en compte dans le transfert d’une demande de lecture. Si l’appareil répond avec un paquet trop volumineux pour la mémoire tampon du client, le comportement de la demande de lecture correspond au type de stratégie défini sur le canal. Si le type de stratégie du canal est ALLOW_PARTIAL_READS, WinUSB ajoute les données restantes au début du transfert suivant. Si ALLOW_PARTIAL_READS n’est pas défini, la demande de lecture échoue. Pour plus d’informations sur les types de stratégie, consultez WinUSB Functions for Pipe Policy Modification.
Si une application transmet la valeur NULL dans le paramètre chevauchement (opération synchrone), l’application doit s’assurer que LengthTransferred n’est pas NULL, même lorsque l’opération de lecture ne produit aucune donnée de sortie.
Si le chevauchement n’est pas NULL (opération asynchrone), LengthTransferred peut être défini sur NULL. Pour une opération qui se chevauche (et si LengthTransferred est une valeur non NULL ), la valeur reçue dans LengthTransferred après WinUsb_ReadPipe retourne n’a aucun sens tant que l’opération superposée n’est pas terminée. Pour récupérer le nombre réel d’octets lus à partir du canal, appelez WinUsb_GetOverlappedResult.
Quand aucune donnée n’est disponible dans le point de terminaison (le canal est vide), WinUsb_ReadPipe ne retourne pas tant qu’il n’y a pas de données dans le canal. Si une condition d’erreur se produit ou que le délai d’expiration spécifié par l’application expire, WinUsb_ReadPipe retourne toujours FALSE. Pour déterminer la raison réelle de cette valeur de retour, appelez toujours GetLastError. Par exemple, dans ces cas, la valeur d’erreur GetLastError indique la raison réelle :
- Si l’application a spécifié une valeur de délai d’expiration dans la stratégie de canal et que ce délai d’expiration expire, WinUsb_ReadPipe retourne FALSE et GetLastError retourne ERROR_SEM_TIMEOUT.
- Si une condition d’erreur se produit lors de la lecture des données à partir du canal, WinUsb_ReadPipe retourne FALSE et GetLastError retourne ERROR_GEN_FAILURE.
Configuration requise
| Condition requise | Valeur |
|---|---|
| Plateforme cible | Universal |
| En-tête | winusb.h (inclure Winusb.h) |
| Bibliothèque | Winusb.lib |
| DLL | Winusb.dll |