WinUsb_GetOverlappedResult-Funktion (winusb.h)

Artikel
03/06/2024

Die WinUsb_GetOverlappedResult-Funktion ruft die Ergebnisse eines überlappenden Vorgangs für die angegebene Datei ab.

Syntax

BOOL WinUsb_GetOverlappedResult(
  [in]  WINUSB_INTERFACE_HANDLE InterfaceHandle,
  [in]  LPOVERLAPPED            lpOverlapped,
  [out] LPDWORD                 lpNumberOfBytesTransferred,
  [in]  BOOL                    bWait
);

Parameter

[in] InterfaceHandle

Ein undurchsichtiges Handle für die erste Schnittstelle auf dem Gerät, das von WinUsb_Initialize zurückgegeben wird.

[in] lpOverlapped

Ein Zeiger auf eine OVERLAPPED-Struktur , die beim Starten des überlappenden Vorgangs angegeben wurde.

[out] lpNumberOfBytesTransferred

Ein Zeiger auf eine Variable, die die Anzahl der Bytes empfängt, die tatsächlich durch einen Lese- oder Schreibvorgang übertragen wurden.

[in] bWait

Wenn dieser Parameter TRUE ist, wird die Funktion erst zurückgegeben, wenn der Vorgang abgeschlossen wurde. Wenn dieser Parameter FALSE ist und der Vorgang noch aussteht, gibt die Funktion FALSE zurück, und die GetLastError-Funktion gibt ERROR_IO_INCOMPLETE zurück.

Rückgabewert

Wenn die Funktion erfolgreich ist, ist der Rückgabewert eine andere Zahl als 0. Wenn die Funktion fehlerhaft ist, ist der Rückgabewert null. Um erweiterte Fehlerinformationen zu erhalten, rufen Sie GetLastError auf.

Hinweise

Diese Funktion ähnelt der Win32-API-Routine GetOverlappedResult mit einem Unterschied: Anstatt ein Dateihandle zu übergeben, das von CreateFile zurückgegeben wird, übergibt der Aufrufer ein Schnittstellenhandle, das von WinUsb_Initialize zurückgegeben wird. Der Aufrufer kann beide API-Routinen verwenden, wenn das entsprechende Handle übergeben wird. Die WinUsb_GetOverlappedResult-Funktion extrahiert das Dateihandle aus dem Schnittstellenhandle und ruft dann GetOverlappedResult auf.

Die Ergebnisse, die von der WinUsb_GetOverlappedResult-Funktion gemeldet werden, sind die Ergebnisse des letzten überlappenden Vorgangs des angegebenen Handles, für den die angegebene OVERLAPPED-Struktur bereitgestellt wurde und für die die Ergebnisse des Vorgangs ausstehen. Ein ausstehender Vorgang wird angezeigt, wenn die Funktion, die den Vorgang gestartet hat, FALSE und die GetLastError-Routine ERROR_IO_PENDING zurückgibt. Wenn ein E/A-Vorgang aussteht, setzt die Funktion, die den Vorgang gestartet hat, den hEvent-Member der OVERLAPPED-Struktur auf den nicht signalierten Zustand zurück. Wenn der ausstehende Vorgang abgeschlossen wurde, legt das System das Ereignisobjekt auf den signalierten Zustand fest.

Der Aufrufer kann angeben, dass ein Ereignisobjekt in der OVERLAPPED-Struktur manuell zurückgesetzt wird. Wenn ein Ereignisobjekt zum automatischen Zurücksetzen verwendet wird, darf das Ereignishandle in keinem anderen Wartevorgang im Intervall zwischen dem Starten des überlappenden Vorgangs und dem Aufruf von WinUsb_GetOverlappedResult angegeben werden. Beispielsweise wird das Ereignisobjekt manchmal in einer der Warteroutinen angegeben, um auf den Abschluss des Vorgangs zu warten. Wenn die Warteroutine zurückgegeben wird, legt das System den Zustand eines Ereignisses für das automatische Zurücksetzen auf nicht signalisiert fest, und ein aufeinanderfolgender Aufruf von WinUsb_GetOverlappedResult , bei dem der bWait-Parameter auf TRUE festgelegt ist, bewirkt, dass die Funktion auf unbestimmte Zeit blockiert wird.

Wenn der bWait-ParameterTRUE ist, bestimmt WinUsb_GetOverlappedResult , ob der ausstehende Vorgang abgeschlossen wurde, indem darauf gewartet wird, dass sich das Ereignisobjekt im signalierten Zustand befindet.

Wenn das hEvent-Element der OVERLAPPED-StrukturNULL ist, verwendet das System den Zustand des Dateihandles, um zu signalisieren, wenn der Vorgang abgeschlossen wurde. Verwenden Sie für diesen Zweck keine Dateihandles. Es ist besser, ein Ereignisobjekt aufgrund der Verwirrung zu verwenden, die auftreten kann, wenn mehrere gleichzeitige überlappende Vorgänge für dieselbe Datei ausgeführt werden. In dieser Situation können Sie nicht wissen, welcher Vorgang dazu geführt hat, dass der Zustand des Objekts signalisiert wird.