Freigeben über


WinUsb_ReadPipe-Funktion (winusb.h)

Die WinUsb_ReadPipe-Funktion liest Daten aus der angegebenen Pipe.

Syntax

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

Parameter

[in] InterfaceHandle

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

Um Daten aus der Pipe zu lesen, 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.

[out] Buffer

Ein vom Aufrufer zugewiesener Puffer, der die gelesenen Daten empfängt.

[in] BufferLength

Die maximale Anzahl der zu lesenden 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 Buffer kopiert 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_ReadPipe sofort zurückgegeben, anstatt synchron darauf zu warten, dass der Vorgang abgeschlossen ist, bevor er zurückgegeben wird. Nach Abschluss des Vorgangs wird ein Ereignis signalisiert.

Rückgabewert

WinUsb_ReadPipe 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
Ein überlappender E/A-Vorgang wird ausgeführt, ist aber noch nicht abgeschlossen. 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
Es ist nicht genügend Arbeitsspeicher vorhanden, um den Vorgang auszuführen.
ERROR_SEM_TIMEOUT
Der von WinUsb_ReadPipe im USB-Stapel initiierte Lesevorgang hat ein Timeout ausgeführt, bevor der Vorgang abgeschlossen werden konnte.

Hinweise

Wenn die vom Gerät zurückgegebenen Daten größer als eine maximale Übertragungslänge sind, unterteilt WinUSB die Anforderung in kleinere Anforderungen mit maximaler Übertragungslänge und sendet sie seriell. Wenn die Übertragungslänge kein Vielfaches der maximalen Paketgröße des Endpunkts ist (abrufbar über den MaximumPacketSize-Member der WINUSB_PIPE_INFORMATION-Struktur), erhöht WinUSB die Größe der Übertragung auf das nächste Vielfache von MaximumPacketSize.

Die USB-Paketgröße berücksichtigt die Übertragung für eine Leseanforderung nicht. Wenn das Gerät mit einem Paket antwortet, das für den Clientpuffer zu groß ist, entspricht das Verhalten der Leseanforderung dem Typ der in der Pipe festgelegten Richtlinie. Wenn der Richtlinientyp für die Pipe ALLOW_PARTIAL_READS ist, fügt WinUSB die restlichen Daten zu Beginn der nächsten Übertragung hinzu. Wenn ALLOW_PARTIAL_READS nicht festgelegt ist, schlägt die Leseanforderung fehl. Weitere Informationen zu Richtlinientypen finden Sie unter WinUSB Functions for Pipe Policy Modification.

Wenn eine Anwendung NULL im Überlappungsparameter (synchroner Vorgang) übergibt, muss die Anwendung sicherstellen, dass LengthTransferred nicht NULL ist, auch wenn der Lesevorgang 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_ReadPipe rückgaben empfangen wird, bedeutungslos, bis der überlappende Vorgang abgeschlossen ist. Um die tatsächliche Anzahl der aus der Pipe gelesenen Bytes abzurufen, rufen Sie WinUsb_GetOverlappedResult auf.

Wenn keine Daten im Endpunkt verfügbar sind (Pipe ist leer), wird WinUsb_ReadPipe erst zurückgegeben, wenn sich Daten in der Pipe befinden. Wenn eine Fehlerbedingung auftritt oder das von der Anwendung angegebene Timeout abläuft, gibt WinUsb_ReadPipe immer FALSE zurück. Um den tatsächlichen Grund für diesen Rückgabewert zu ermitteln, rufen Sie immer GetLastError auf. In diesen Fällen gibt beispielsweise der GetLastError-Fehlerwert den tatsächlichen Grund an:

  • Wenn die Anwendung einen Timeoutwert in der Piperichtlinie angegeben hat und dieses Timeout abläuft, gibt WinUsb_ReadPipe FALSE und GetLastError ERROR_SEM_TIMEOUT zurück.
  • Wenn beim Lesen von Daten aus der Pipe eine Fehlerbedingung auftritt, gibt WinUsb_ReadPipe FALSE und GetLastError ERROR_GEN_FAILURE zurück.

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