WinUsb_WritePipe-Funktion (winusb.h)

Artikel
08/27/2023

Die WinUsb_WritePipe-Funktion schreibt Daten in eine Pipe.

Syntax

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
);

Parameter

[in] InterfaceHandle

Ein undurchsichtiges Handle für die Schnittstelle, das den Endpunkt enthält, dem die Pipe zugeordnet ist.

Um in eine Pipe zu schreiben, die einem Endpunkt in der ersten Schnittstelle zugeordnet ist, verwenden Sie das von WinUsb_Initialize zurückgegebene Handle. Verwenden Sie für alle anderen Schnittstellen das Handle für die Zielschnittstelle, die von WinUsb_GetAssociatedInterface abgerufen wird.

[in] PipeID

PipeID entspricht dem Feld bEndpointAddress im Endpunktdeskriptor. Informationen zum Layout dieses Felds finden Sie in Tabelle 9-13 in "Universal Serial Bus Specification Revision 2.0" unter USB Technology. Im Feld bEndpointAddress gibt Bit 7 die Richtung des Endpunkts an: 0 für OUT; 1 für IN.

[in] Buffer

Ein vom Aufrufer zugewiesener Puffer, der die zu schreibenden Daten enthält.

[in] BufferLength

Die Anzahl der zu schreibenden Bytes. Diese Zahl muss kleiner oder gleich der Größe von Puffer in Bytes sein.

[out, optional] LengthTransferred

Ein Zeiger auf eine ULONG-Variable, die die tatsächliche Anzahl von Bytes empfängt, die in die Pipe geschrieben wurden. Weitere Informationen finden Sie in den Hinweisen.

[in, optional] Overlapped

Ein optionaler Zeiger auf eine OVERLAPPED-Struktur, die für asynchrone Vorgänge verwendet wird. Wenn dieser Parameter angegeben wird, wird WinUsb_WritePipe sofort zurückgegeben, und das Ereignis wird signalisiert, wenn der Vorgang abgeschlossen ist.

Rückgabewert

WinUsb_WritePipe gibt TRUE zurück, wenn der Vorgang erfolgreich ist. Andernfalls gibt diese Funktion FALSE zurück, und der Aufrufer kann den protokollierten Fehler abrufen, indem er GetLastError aufruft.

GetLastError kann den folgenden Fehlercode zurückgeben.

Rückgabecode	Beschreibung
ERROR_INVALID_HANDLE	Der Aufrufer hat NULL im Parameter InterfaceHandle übergeben.
ERROR_IO_PENDING	Gibt an, dass ein überlappender E/A-Vorgang ausgeführt, aber noch nicht abgeschlossen wurde. Wenn der überlappende Vorgang nicht sofort abgeschlossen werden kann, gibt die Funktion FALSE zurück, und die GetLastError-Funktion gibt ERROR_IO_PENDING zurück, was angibt, dass der Vorgang im Hintergrund ausgeführt wird. Rufen Sie WinUsb_GetOverlappedResult auf, um den Erfolg oder Fehler des Vorgangs zu überprüfen.
ERROR_NOT_ENOUGH_MEMORY	Gibt an, dass nicht genügend Arbeitsspeicher zum Ausführen des Vorgangs vorhanden ist.
ERROR_SEM_TIMEOUT	Der von WinUsb_WritePipe im USB-Stapel initiierte Schreibvorgang hat ein Timeout ausgeführt, bevor der Vorgang abgeschlossen werden konnte.

Hinweise

Um eine Schreibanforderung zu erstellen, muss die Anwendung einen Puffer zuordnen, ihn mit den Daten füllen, die Sie auf das Gerät schreiben möchten, und den Puffer durch Aufrufen WinUsb_WritePipe an den Hostcontroller senden.

Die folgenden Einschränkungen gelten für die Größe des Puffers, wenn RAW_IO festgelegt ist:

Die Pufferlänge muss ein Vielfaches der maximalen Endpunktpaketgröße sein.
Die Länge muss kleiner oder gleich dem Wert von MAXIMUM_TRANSFER_SIZE sein, die von WinUsb_GetPipePolicy abgerufen werden.

Es gibt keine Einschränkungen für die Größe des Puffers, wenn RAW_IO nicht als Richtlinientyp der Pipe festgelegt ist. Wenn die Größe des Puffers größer als die von MAXIMUM_TRANSFER_SIZE gemeldete maximale Übertragungslänge ist, unterteilt WinUSB die Anforderung in kleinere Anforderungen und sendet sie seriell an den Hostcontroller.

Eine Schreibanforderung, die Daten der Länge null enthält, wird über den USB-Stapel weitergeleitet.

Wenn eine Anwendung NULL im Überlappungsparameter (synchroner Vorgang) übergibt, muss sie sicherstellen, dass LengthTransferred nicht NULL ist, auch wenn ein Vorgang keine Ausgabedaten erzeugt.

Wenn Overlapped nicht NULL (asynchroner Vorgang) ist, kann LengthTransferred auf NULL festgelegt werden. Für einen überlappenden Vorgang (und wenn LengthTransferred ein Wert ohne NULL ist) ist der wert, der in LengthTransferred nach WinUsb_WritePipe rückgaben empfangen wird, bedeutungslos, bis der überlappende Vorgang abgeschlossen ist. Um die tatsächliche Anzahl der zurückgegebenen Bytes abzurufen, rufen Sie WinUsb_GetOverlappedResult auf.

Anforderungen

Anforderung	Wert
Zielplattform	Universell
Header	winusb.h (einschließlich Winusb.h)
Bibliothek	Winusb.lib
DLL	Winusb.dll

Weitere Informationen

Winusb

WinUSB-Funktionen

WinUsb_Initialize

Freigeben über