Função GetQueuedCompletionStatusEx (ioapiset.h)

Artigo
08/24/2023

Recupera várias entradas de porta de conclusão simultaneamente. Ela aguarda a conclusão das operações de E/S pendentes associadas à porta de conclusão especificada.

Para remover um pacote de conclusão de E/S de cada vez, use a função GetQueuedCompletionStatus.

Sintaxe

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

Parâmetros

[in] CompletionPort

Um identificador para a porta de conclusão. Para criar uma porta de conclusão, use a função CreateIoCompletionPort.

[out] lpCompletionPortEntries

Na entrada, aponta para uma matriz pré-alocada de estruturas OVERLAPPED_ENTRY.

Na saída, recebe uma matriz de estruturas OVERLAPPED_ENTRY que mantêm as entradas. O número de elementos de matriz é fornecido por ulNumEntriesRemoved.

O número de bytes transferidos durante cada E/S, a chave de conclusão que indica em qual arquivo ocorreu cada E/S e o endereço de estrutura sobreposto usado em cada E/S original são todos retornados na matriz lpCompletionPortEntries.

[in] ulCount

O número máximo de entradas a serem removidas.

[out] ulNumEntriesRemoved

Um ponteiro para uma variável que recebe o número de entradas de fato removidas.

[in] dwMilliseconds

O número de milissegundos que o chamador está disposto a aguardar para que um pacote de conclusão apareça na porta de conclusão. Se um pacote de conclusão não aparecer dentro do tempo especificado, a função atingirá o tempo limite e retornará FALSE.

Se dwMilliseconds for INFINITE (0xFFFFFFFF), a função nunca atingirá o tempo limite. Se dwMilliseconds for zero e não houver nenhuma operação de E/S para remover da fila, a função atingirá o tempo limite imediatamente.

Windows XP, Windows Server 2003, Windows Vista, Windows 7, Windows Server 2008 e Windows Server 2008 R2: O valor dwMilliseconds inclui o tempo gasto em estados de baixa potência. Por exemplo, o tempo limite continua em contagem regressiva enquanto o computador está dormindo.

Windows 8, Windows Server 2012, Windows 8.1, Windows Server 2012 R2, Windows 10 e Windows Server 2016: o valor dwMilliseconds não inclui o tempo gasto em estados de baixa potência. Por exemplo, o tempo limite não continua a contagem regressiva enquanto o computador está dormindo.

[in] fAlertable

Se esse parâmetro for FALSE, a função não retornará até que o período de tempo limite tenha decorrido ou uma entrada seja recuperada.

Se o parâmetro for TRUE e não houver entradas disponíveis, a função executará uma espera alertável. O thread retorna quando o sistema coloca na fila uma rotina de conclusão de E/S ou APC para o thread e o thread executa a função.

Uma rotina de conclusão é colocada na fila quando a função ReadFileEx ou WriteFileEx na qual ela foi especificada foi concluída e o thread de chamada é o thread que iniciou a operação. Um APC é enfileirado quando você chama QueueUserAPC.

Valor retornado

Retorna (TRUE) diferente de zero se tiver êxito, caso contrário, (FALSE) zero.

Para obter informações de erro estendidas, chame GetLastError.

Comentários

Essa função associa um thread à porta de conclusão especificada. Um thread pode ser associado a no máximo uma porta de conclusão.

Essa função retorna TRUE quando pelo menos uma E/S pendente é concluída, mas é possível que uma ou mais operações de E/S tenham falhado. Observe que cabe ao usuário dessa função verificar a lista de entradas retornadas no parâmetro lpCompletionPortEntries para determinar qual delas corresponde às possíveis operações de E/S com falha examinando o status contido no membro lpOverlapped em cada OVERLAPPED_ENTRY.

Essa função retorna FALSE quando nenhuma operação de E/S foi removida da fila. Isso normalmente significa que ocorreu um erro ao processar os parâmetros para essa chamada ou que o identificador CompletionPort foi fechado ou é inválido. A função GetLastError fornece informações de erro estendidas.

Se uma chamada para GetQueuedCompletionStatusEx falhar porque o identificador associado a ele está fechado, a função retornará FALSE e GetLastError retornará ERROR_ABANDONED_WAIT_0.

Os aplicativos de servidor podem ter vários threads chamando a função GetQueuedCompletionStatusEx para a mesma porta de conclusão. À medida que as operações de E/S são concluídas, elas são colocadas na fila dessa porta pela ordem de primeiro a entrar, primeiro a sair. Se um thread estiver aguardando ativamente essa chamada, uma ou mais solicitações na fila concluirão a chamada somente para esse thread.

Para obter mais informações sobre a teoria da porta de conclusão de E/S, o uso e as funções associadas, consulte Portas de conclusão de E/S.

No Windows 8 e Windows Server 2012, essa função é compatível com as tecnologias a seguir.

Tecnologia	Com suporte
Protocolo SMB (SMB) 3.0	Sim
TFO (Failover transparente) do SMB 3.0	Sim
SMB 3.0 com compartilhamentos de arquivos de expansão (SO)	Sim
Sistema de arquivos de Volume Compartilhado Clusterizado (CsvFS)	Sim
ReFS (Sistema de Arquivos Resiliente)	Sim

Requisitos

Requisito	Valor
Cliente mínimo com suporte	Windows Vista [aplicativos da área de trabalho \| Aplicativos UWP]
Servidor mínimo com suporte	Windows Server 2008 [aplicativos da área de trabalho \| Aplicativos UWP]
Plataforma de Destino	Windows
Cabeçalho	ioapiset.h (inclua Windows.h)
Biblioteca	Kernel32.lib
DLL	Kernel32.dll