Funzione GetOverlappedResultEx (ioapiset.h)

Articolo
05/30/2024

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