Funzione GetQueuedCompletionStatusEx (ioapiset.h)

Articolo
11/08/2024

Recupera più voci di porta di completamento contemporaneamente. Attende il completamento delle operazioni di I/O in sospeso associate alla porta di completamento specificata.

Per annullare la coda dei pacchetti di completamento di I/O uno alla volta, usare la funzione GetQueuedCompletionStatus.

Sintassi

BOOL GetQueuedCompletionStatusEx(
  [in]  HANDLE             CompletionPort,
  [out] LPOVERLAPPED_ENTRY lpCompletionPortEntries,
  [in]  ULONG              ulCount,
  [out] PULONG             ulNumEntriesRemoved,
  [in]  DWORD              dwMilliseconds,
  [in]  BOOL               fAlertable
);

Parametri

[in] CompletionPort

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

[out] lpCompletionPortEntries

In caso di input, punta a una matrice preallocata di strutture OVERLAPPED_ENTRY.

Nell'output, riceve una matrice di strutture OVERLAPPED_ENTRY che contengono le voci. Il numero di elementi della matrice viene fornito da ulNumEntriesRemoved.

Il numero di byte trasferiti durante ogni I/O, la chiave di completamento che indica in quale file si è verificato ogni I/O e l'indirizzo della struttura sovrapposta usato in ogni I/O originale vengono tutti restituiti nella lpCompletionPortEntries matrice.

[in] ulCount

Numero massimo di voci da rimuovere.

[out] ulNumEntriesRemoved

Puntatore a una variabile che riceve il numero di voci effettivamente rimosse.

[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 il tempo specificato, la funzione raggiunge il timeout e restituisce FALSE.

Se dwMilliseconds è infinite (0xFFFFFFFF), la funzione non si verifica mai. Se dwMilliseconds è zero e non è presente alcuna operazione di I/O da rimuovere dalla coda, la funzione si verifica immediatamente.

Windows XP, Windows Server 2003, Windows Vista, Windows 7, Windows Server 2008 e Windows Server 2008 R2: Il valore dwMilliseconds include il tempo impiegato in stati a basso consumo. Ad esempio, il timeout continua a contare mentre il computer è in stato di sospensione.

Windows 8 e versioni successive, Windows Server 2012 e versioni successive: Il valore dwMilliseconds non include il tempo impiegato in stati a basso consumo. Ad esempio, il timeout non continua a contare mentre il computer è in stato di sospensione.

[in] fAlertable

Se questo parametro è FALSE, la funzione non restituisce finché non è trascorso il periodo di timeout o viene recuperata una voce.

Se il parametro è TRUE e non sono disponibili voci, la funzione esegue un'attesa avvisabile. Il thread viene restituito quando il sistema accoda una routine di completamento I/O o APC al thread e il thread esegue la funzione.

Una routine di completamento viene accodata quando la funzione ReadFileEx o WriteFileEx in cui è stata specificata e il thread chiamante è il thread che ha avviato l'operazione. Un APC viene accodato quando si chiama QueueUserAPC.

Valore restituito

Restituisce un valore diverso da zero (TRUE) se ha esito positivo o zero (FALSE) in caso contrario.

Per ottenere informazioni estese sull'errore, chiamare GetLastError.

Osservazioni

Questa funzione associa un thread alla porta di completamento specificata. Un thread può essere associato al massimo a una porta di completamento.

Questa funzione restituisce TRUE quando almeno un I/O in sospeso viene completato, ma è possibile che una o più operazioni di I/O non siano riuscite. Si noti che spetta all'utente di questa funzione controllare l'elenco delle voci restituite nel lpCompletionPortEntries parametro per determinare quale di esse corrisponda a tutte le possibili operazioni di I/O non riuscite esaminando lo stato contenuto nel membro lpOverlapped in ogni OVERLAPPED_ENTRY.

Questa funzione restituisce FALSE quando non è stata dequeuata alcuna operazione di I/O. Ciò significa in genere che si è verificato un errore durante l'elaborazione dei parametri a questa chiamata o che l'handle CompletionPort è stato chiuso o non è valido. La funzione GetLastError fornisce informazioni estese sull'errore.

Se una chiamata a GetQueuedCompletionStatusEx ha esito negativo perché l'handle associato è chiuso, la funzione restituisce FALSE e GetLastError restituirà ERROR_ABANDONED_WAIT_0.

Le applicazioni server possono avere diversi thread che chiamano la funzione GetQueuedCompletionStatusEx per la stessa porta di completamento. Al termine delle operazioni di I/O, vengono accodati a questa porta nell'ordine first-in-first-out. Se un thread è attivamente in attesa di questa chiamata, una o più richieste in coda completano la chiamata solo per tale thread.

Per altre informazioni sulla teoria delle porte di completamento 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	Sostenuto
Protocollo SMB (Server Message Block) 3.0	Sì
SMB 3.0 Transparent Failover (TFO)	Sì
SMB 3.0 con condivisioni file con scalabilità orizzontale (SO)	Sì
Cluster Shared Volume File System (CsvFS)	Sì
Resilient File System (ReFS)	Sì

Fabbisogno

Requisito	Valore
client minimo supportato	Windows Vista [app desktop \| App UWP]
server minimo supportato	Windows Server 2008 [app desktop \| App UWP]
piattaforma di destinazione	Finestre
intestazione	ioapiset.h (include Windows.h)
libreria	Kernel32.lib
dll	Kernel32.dll