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 |
|---|---|
|
Der Aufrufer hat NULL im Parameter InterfaceHandle übergeben. |
|
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. |
|
Es ist nicht genügend Arbeitsspeicher vorhanden, um den Vorgang auszuführen. |
|
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 |