fonction WinUsb_WritePipe (winusb.h)

  • Article

La fonction WinUsb_WritePipe écrit des données dans un canal.

Syntaxe

BOOL WinUsb_WritePipe(
  [in]            WINUSB_INTERFACE_HANDLE InterfaceHandle,
  [in]            UCHAR                   PipeID,
  [in]            PUCHAR                  Buffer,
  [in]            ULONG                   BufferLength,
  [out, optional] PULONG                  LengthTransferred,
  [in, optional]  LPOVERLAPPED            Overlapped
);

Paramètres

[in] InterfaceHandle

Handle opaque de l’interface qui contient le point de terminaison auquel le canal est associé.

Pour écrire dans un 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, consultez le tableau 9-13 dans « Universal Serial Bus Specification Revision 2.0 » à l’adresse Technologie USB. Dans le champ bEndpointAddress , bit 7 indique la direction du point de terminaison : 0 pour OUT ; 1 pour IN.

[in] Buffer

Mémoire tampon allouée à l’appelant qui contient les données à écrire.

[in] BufferLength

Nombre d'octets à écrire. Ce nombre doit être inférieur ou égal à la taille, en octets, de La mémoire tampon.

[out, optional] LengthTransferred

Pointeur vers une variable ULONG qui reçoit le nombre réel d’octets écrits dans le canal. Pour plus d'informations, consultez la section Notes.

[in, optional] Overlapped

Pointeur facultatif vers une structure CHEVAUCHEMENT, qui est utilisé pour les opérations asynchrones. Si ce paramètre est spécifié, WinUsb_WritePipe retourne immédiatement et l’événement est signalé lorsque l’opération est terminée.

Valeur retournée

WinUsb_WritePipe 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
ERROR_INVALID_HANDLE
 L’appelant a passé la valeur NULL dans le paramètre InterfaceHandle .
ERROR_IO_PENDING
 Indique qu’une opération d’E/S qui se chevauche est en cours, mais qu’elle 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.
ERROR_NOT_ENOUGH_MEMORY
 Indique que la mémoire est insuffisante pour effectuer l’opération.
ERROR_SEM_TIMEOUT
 L’opération d’écriture lancée par WinUsb_WritePipe dans la pile USB a expiré avant que l’opération puisse être terminée.

Remarques

Pour créer une demande d’écriture, l’application doit allouer une mémoire tampon, la remplir avec les données que vous souhaitez écrire sur l’appareil et envoyer la mémoire tampon au contrôleur hôte en appelant WinUsb_WritePipe.

Les restrictions suivantes s’appliquent à la taille de la mémoire tampon si RAW_IO est défini :

  • La longueur de la mémoire tampon doit être un multiple de la taille maximale du paquet de point de terminaison.
  • La longueur doit être inférieure ou égale à la valeur de MAXIMUM_TRANSFER_SIZE récupérée par WinUsb_GetPipePolicy.
Il n’existe aucune restriction sur la taille de la mémoire tampon si RAW_IO n’est pas défini comme type de stratégie du canal. Si la taille de la mémoire tampon est supérieure à la longueur de transfert maximale signalée par MAXIMUM_TRANSFER_SIZE, WinUSB divise la requête en requêtes plus petites et les envoie en série au contrôleur hôte.

Une demande d’écriture qui contient des données de longueur nulle est transférée vers le bas de la pile USB.

Si une application transmet la valeur NULL dans le paramètre chevauchement (opération synchrone), elle doit s’assurer que LengthTransferred n’est pas NULL, même lorsqu’une opération ne produit aucune donnée de sortie.

Si le chevauchement n’a pas la valeur 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_WritePipe 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 retournés, appelez WinUsb_GetOverlappedResult.

Configuration requise

Condition requise Valeur
Plateforme cible Universal
En-tête winusb.h (inclure Winusb.h)
Bibliothèque Winusb.lib
DLL Winusb.dll

Voir aussi

WinUSB

Fonctions WinUSB

WinUsb_Initialize