funzione WinUsb_GetOverlappedResult (winusb.h)

Articolo
08/27/2023

La funzione WinUsb_GetOverlappedResult recupera i risultati di un'operazione sovrapposta nel file specificato.

Sintassi

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

Parametri

[in] InterfaceHandle

Handle opaco per la prima interfaccia nel dispositivo, restituito da WinUsb_Initialize.

[in] lpOverlapped

Puntatore a una struttura OVERLAPPED specificata all'avvio dell'operazione sovrapposta.

[out] lpNumberOfBytesTransferred

Puntatore a una variabile che riceve il numero di byte effettivamente trasferiti da un'operazione di lettura o scrittura.

[in] bWait

Se questo parametro è TRUE, la funzione non restituisce fino al completamento dell'operazione. Se questo parametro è FALSE e l'operazione è ancora in sospeso, la funzione restituisce FALSE e la funzione GetLastError restituisce ERROR_IO_INCOMPLETE.

Valore restituito

Se la funzione ha esito positivo, il valore restituito è qualsiasi numero diverso da zero. Se la funzione ha esito negativo, il valore restituito è zero. Per informazioni dettagliate sull'errore, chiamare GetLastError.

Commenti

Questa funzione è simile alla routine API Win32, GetOverlappedResult, con una differenza, anziché passare un handle di file restituito da CreateFile, il chiamante passa un handle di interfaccia restituito da WinUsb_Initialize. Il chiamante può usare una routine API, se l'handle appropriato viene passato. La funzione WinUsb_GetOverlappedResult estrae l'handle di file dall'handle dell'interfaccia e quindi chiama GetOverlappedResult.

I risultati segnalati dalla funzione WinUsb_GetOverlappedResult sono quelli dell'ultima operazione sovrapposta dell'handle specificato a cui è stata fornita la struttura OVERLAPPED specificata e per cui i risultati dell'operazione erano in sospeso. Un'operazione in sospeso è indicata quando la funzione che ha avviato l'operazione restituisce FALSE e la routine GetLastError restituisce ERROR_IO_PENDING. Quando un'operazione di I/O è in sospeso, la funzione che ha avviato l'operazione reimposta il membro hEvent della struttura OVERLAPPED allo stato non firmato. Quando l'operazione in sospeso è stata completata, il sistema imposta l'oggetto evento sullo stato segnalato.

Il chiamante può specificare che un oggetto evento viene reimpostato manualmente nella struttura OVERLAPPED . Se viene usato un oggetto evento di reimpostazione automatica, l'handle eventi non deve essere specificato in qualsiasi altra operazione di attesa nell'intervallo tra l'avvio dell'operazione sovrapposta e la chiamata a WinUsb_GetOverlappedResult. Ad esempio, l'oggetto evento viene talvolta specificato in una delle routine di attesa per attendere il completamento dell'operazione. Quando la routine di attesa viene restituita, il sistema imposta lo stato di un evento di reimpostazione automatica su non firmato e una chiamata successiva a WinUsb_GetOverlappedResult con il parametro bWait impostato su TRUE causa il blocco indefinito della funzione.

Se il parametro bWait è TRUE, WinUsb_GetOverlappedResult determina se l'operazione in sospeso è stata completata aspettando che l'oggetto evento sia nello stato segnalato.

Se il membro hEvent della struttura OVERLAPPED è NULL, il sistema usa lo stato dell'handle file per segnalare quando l'operazione è stata completata. Non usare handle di file per questo scopo. È preferibile usare un oggetto evento a causa della confusione che può verificarsi quando vengono eseguite più operazioni sovrapposte simultanee sullo stesso file. In questa situazione non è possibile sapere quale operazione ha causato il segnale dello stato dell'oggetto.