Funzione GetQueuedCompletionStatus (ioapiset.h)

Articolo
05/20/2023

Tenta di dequeare un pacchetto di completamento di I/O dalla porta di completamento di I/O specificata. Se non è presente alcuna coda di pacchetti di completamento, la funzione attende il completamento di un'operazione di I/O in sospeso associata alla porta di completamento.

Per dequeuere più pacchetti di completamento di I/O contemporaneamente, usare la funzione GetQueuedCompletionStatusEx .

Sintassi

BOOL GetQueuedCompletionStatus(
  [in]  HANDLE       CompletionPort,
        LPDWORD      lpNumberOfBytesTransferred,
  [out] PULONG_PTR   lpCompletionKey,
  [out] LPOVERLAPPED *lpOverlapped,
  [in]  DWORD        dwMilliseconds
);

Parametri

[in] CompletionPort

Handle alla porta di completamento. Per creare una porta di completamento, usare la funzione CreateIoCompletionPort .

lpNumberOfBytesTransferred

Puntatore a una variabile che riceve il numero di byte trasferiti in un'operazione di I/O completata.

[out] lpCompletionKey

Puntatore a una variabile che riceve il valore della chiave di completamento associato all'handle di file il cui operazione di I/O è stata completata. Una chiave di completamento è una chiave per file specificata in una chiamata a CreateIoCompletionPort.

[out] lpOverlapped

Puntatore a una variabile che riceve l'indirizzo della struttura OVERLAPPED specificata all'avvio dell'operazione di I/O completata.

Anche se è stata passata la funzione un handle di file associato a una porta di completamento e una struttura OVERLAPPED valida, un'applicazione può impedire la notifica della porta di completamento. Questa operazione viene eseguita specificando un handle di eventi valido per il membro hEvent della struttura OVERLAPPED e impostando il relativo bit a basso ordine. Un handle di eventi valido il cui bit a basso ordine è impostato impedisce il completamento dell'I/O sovrapposto di eseguire l'esecuzione di un pacchetto di completamento alla porta di completamento.

[in] dwMilliseconds

Numero di millisecondi che il chiamante è disposto ad attendere la visualizzazione di un pacchetto di completamento nella porta di completamento. Se un pacchetto di completamento non viene visualizzato entro l'ora specificata, la funzione timeout, restituisce FALSE e imposta *lpOverlapped su NULL.

Se dwMilliseconds è INFINITE, la funzione non verrà mai timeout. Se dwMilliseconds è zero e non esiste alcuna operazione di I/O da dequeue, la funzione timeout immediatamente.

Windows XP, Windows Server 2003, Windows Vista, Windows 7, Windows Server 2008 e Windows Server 2008 R2: Il valore dwMilliseconds include tempo trascorso in stati di bassa potenza. Ad esempio, il timeout continua a contare mentre il computer è inattivo.

Windows 8, Windows Server 2012, Windows 8.1, Windows Server 2012 R2, Windows 10 e Windows Server 2016: il valore dwMilliseconds non include tempo trascorso in bassa potenza Stati. Ad esempio, il timeout non continua il conteggio mentre il computer è inattivo.

Valore restituito

Restituisce non zero (TRUE) se ha esito positivo o zero (FALSE) in caso contrario.

Per informazioni dettagliate sull'errore, chiamare GetLastError.

Per altre informazioni, vedere la sezione Osservazioni.

Commenti

Questa funzione associa un thread alla porta di completamento specificata. Un thread può essere associato alla maggior parte di una porta di completamento.

Se una chiamata a GetQueuedCompletionStatus ha esito negativo perché l'handle della porta di completamento associato a esso è chiuso mentre la chiamata è in sospeso, la funzione restituisce FALSE, *lpOverlapped sarà NULL e GetLastError restituirà ERROR_ABANDONED_WAIT_0.

Windows Server 2003 e Windows XP: La chiusura dell'handle della porta di completamento mentre una chiamata è in sospeso non comporterà il comportamento indicato in precedenza. La funzione continuerà ad attendere fino a quando non viene rimossa una voce dalla porta o fino a quando non si verifica un timeout, se specificato come valore diverso da INFINITE.

Se la funzione GetQueuedCompletionStatus ha esito positivo, ha dequeuato un pacchetto di completamento per un'operazione di I/O riuscita dalla porta di completamento e ha archiviato le informazioni nelle variabili a cui puntano i parametri seguenti: lpNumberOfBytes, lpCompletionKey e lpOverlapped. In caso di errore (il valore restituito è FALSE), questi stessi parametri possono contenere combinazioni di valori particolari come indicato di seguito:

Se *lpOverlapped è NULL, la funzione non ha dequeueto un pacchetto di completamento dalla porta di completamento. In questo caso, la funzione non archivia le informazioni nelle variabili a cui puntano i parametri lpNumberOfBytes e lpCompletionKey e i relativi valori sono indeterminato.
Se *lpOverlapped non è NULL e la funzione dequeue un pacchetto di completamento per un'operazione di I/O non riuscita dalla porta di completamento, la funzione archivia informazioni sull'operazione non riuscita nelle variabili puntate da lpNumberOfBytes, lpCompletionKey e lpOverlapped. Per informazioni dettagliate sull'errore, chiamare GetLastError.

Per altre informazioni sulla teoria della porta di completamento di I/O, sull'utilizzo e sulle funzioni associate, vedere Porte di completamento I/O.

In Windows 8 e Windows Server 2012 questa funzione è supportata dalle tecnologie seguenti.

Tecnologia	Supportato
Protocollo SMB (Server Message Block) 3.0	Sì
Failover trasparente SMB 3.0 (TFO)	Sì
SMB 3.0 con condivisioni file con scalabilità orizzontale (SO)	Sì
File system del volume condiviso del cluster (CsvFS)	Sì
File system resiliente (ReFS)	Sì

Requisiti


Client minimo supportato	Windows XP [app desktop \| App UWP]
Server minimo supportato	Windows Server 2003 [app desktop \| App UWP]
Piattaforma di destinazione	Windows
Intestazione	ioapiset.h (includere Windows.h)
Libreria	Kernel32.lib
DLL	Kernel32.dll