Funzione GetOverlappedResultEx (ioapiset.h)
Recupera i risultati di un'operazione sovrapposta nel file specificato, denominata pipe o dispositivo di comunicazione entro l'intervallo di timeout specificato. Il thread chiamante può eseguire un'attesa avvisabile.
Sintassi
BOOL GetOverlappedResultEx(
[in] HANDLE hFile,
[in] LPOVERLAPPED lpOverlapped,
[out] LPDWORD lpNumberOfBytesTransferred,
[in] DWORD dwMilliseconds,
[in] BOOL bAlertable
);
Parametri
[in] hFile
Handle al file, denominato pipe o dispositivo di comunicazione. Si tratta dello stesso handle specificato quando l'operazione sovrapposta è stata avviata da una chiamata alla funzione ReadFile, WriteFile, ConnectNamedPipe, TransactNamedPipe, DeviceIoControl o WaitCommEvent.
[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. Per un'operazione TransactNamedPipe , si tratta del numero di byte letti dalla pipe. Per un'operazione DeviceIoControl , si tratta del numero di byte di dati di output restituiti dal driver del dispositivo. Per un'operazione ConnectNamedPipe o WaitCommEvent , questo valore non è definito.
[in] dwMilliseconds
Intervallo di timeout, in millisecondi.
Se dwMilliseconds è zero e l'operazione è ancora in corso, la funzione restituisce immediatamente e la funzione GetLastError restituisce ERROR_IO_INCOMPLETE.
Se dwMilliseconds è diverso da zero e l'operazione è ancora in corso, la funzione attende fino a quando l'oggetto non viene segnalato, una routine di completamento di I/O o o è in coda o APC o l'intervallo trascorso prima di restituire. Usare GetLastError per ottenere informazioni sull'errore estese.
Se dwMilliseconds è INFINITE, la funzione restituisce solo quando l'oggetto viene segnalato o una routine di completamento di I/O o viene accodata.
Il valore dwMilliseconds non include tempo trascorso in stati di bassa potenza. Ad esempio, il timeout non continua il conteggio mentre il computer è inattivo.
[in] bAlertable
Se questo parametro è TRUE e il thread chiamante si trova nello stato di attesa, la funzione restituisce quando il sistema accoda una routine di completamento I/O o APC. Il thread chiamante esegue quindi la routine o la funzione. In caso contrario, la funzione non restituisce e la routine di completamento o la funzione APC non viene eseguita.
Una routine di completamento viene accodata quando è stata completata la funzione ReadFileEx o WriteFileEx in cui è stato specificato. La funzione restituisce e la routine di completamento viene chiamata solo se bAlertable è TRUE e il thread chiamante è il thread che ha avviato l'operazione di lettura o scrittura. Un APC viene accodato quando si chiama QueueUserAPC.
Valore restituito
Se la funzione ha esito positivo, il valore restituito è diverso da zero.
Se la funzione ha esito negativo, il valore restituito è zero. Per informazioni dettagliate sull'errore, chiamare GetLastError. I codici di errore comuni includono quanto segue:
- Se dwMilliseconds è zero e l'operazione è ancora in corso, GetLastError restituisce ERROR_IO_INCOMPLETE.
- Se dwMilliseconds è diverso da zero e viene accodata una routine di completamento di I/O o APC, GetLastError restituisce WAIT_IO_COMPLETION.
- Se dwMilliseconds è diverso da zero e l'intervallo di timeout specificato scade, GetLastError restituisce WAIT_TIMEOUT.
Commenti
La funzione GetOverlappedResultEx differisce da GetOverlappedResult nei modi seguenti: il parametro dwMilliseconds può specificare un intervallo di timeout per l'operazione e il parametro bAlertable può specificare che il thread chiamante deve eseguire un'attesa avvisabile.
I risultati segnalati dalla funzione GetOverlappedResultEx 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 funzione 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.
Specificare un oggetto evento di reimpostazione manuale 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 GetOverlappedResultEx. Ad esempio, l'oggetto evento viene talvolta specificato in una delle funzioni di attesa per attendere il completamento dell'operazione. Quando la funzione di attesa viene restituita, il sistema imposta lo stato dell'evento di reimpostazione automatica su non firmato e una chiamata successiva a GetOverlappedResultEx con il parametro dwMilliseconds impostato su INFINITE causa il blocco indefinito della funzione.
Se il membro hEvent della struttura OVERLAPPED è NULL, il sistema usa lo stato dell'handle hFile per segnalare al termine dell'operazione. L'uso di file, pipe denominate o handle di dispositivi di comunicazione per questo scopo è sconsigliato. È più sicuro usare un oggetto evento a causa della confusione che può verificarsi quando vengono eseguite più operazioni sovrapposte simultanee sullo stesso file, la pipe denominata o il dispositivo di comunicazione. In questa situazione non è possibile sapere quale operazione ha causato il segnale dello stato dell'oggetto.
Requisiti
| Requisito | Valore |
|---|---|
| Client minimo supportato | Windows 8 [app desktop | App UWP] |
| Server minimo supportato | Windows Server 2012 [app desktop | App UWP] |
| Piattaforma di destinazione | Windows |
| Intestazione | ioapiset.h (includere Windows.h) |
| Libreria | Kernel32.lib |
| DLL | Kernel32.dll |