Função GetQueuedCompletionStatus (ioapiset.h)

Tenta remover um pacote de conclusão de E/S da porta de conclusão de E/S especificada. Se não houver nenhum pacote de conclusão na fila, a função aguardará a conclusão de uma operação de E/S pendente associada à porta de conclusão.

Para remover vários pacotes de conclusão de E/S de uma só vez, use a função GetQueuedCompletionStatusEx .

Sintaxe

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

Parâmetros

[in] CompletionPort

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

lpNumberOfBytesTransferred

Um ponteiro para uma variável que recebe o número de bytes transferidos em uma operação de E/S concluída.

[out] lpCompletionKey

Um ponteiro para uma variável que recebe o valor da chave de conclusão associado ao identificador de arquivo cuja operação de E/S foi concluída. Uma chave de conclusão é uma chave por arquivo especificada em uma chamada para CreateIoCompletionPort.

[out] lpOverlapped

Um ponteiro para uma variável que recebe o endereço da estrutura OVERLAPPED que foi especificada quando a operação de E/S concluída foi iniciada.

Mesmo que você tenha passado à função um identificador de arquivo associado a uma porta de conclusão e a uma estrutura OVERLAPPED válida, um aplicativo poderá impedir a notificação de porta de conclusão. Isso é feito especificando um identificador de evento válido para o membro hEvent da estrutura OVERLAPPED e definindo seu bit de baixa ordem. Um identificador de evento válido cujo bit de baixa ordem é definido impede a conclusão da E/S sobreposta de enfileirar um pacote de conclusão para a porta de conclusão.

[in] dwMilliseconds

O número de milissegundos que o chamador está disposto a aguardar até 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, retornará FALSE e definirá *lpOverlapped como NULL.

Se dwMilliseconds for INFINITE, a função nunca terá tempo limite. Se dwMilliseconds for zero e não houver nenhuma operação de E/S para remover a fila, a função acabará 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 energia. 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 baixa potência Estados. Por exemplo, o tempo limite não continua em contagem regressiva enquanto o computador está dormindo.

Retornar valor

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

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

Para obter mais informações, consulte a seção Comentários.

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.

Se uma chamada para GetQueuedCompletionStatus falhar porque o identificador de porta de conclusão associado a ele está fechado enquanto a chamada estiver pendente, a função retornará FALSE, *lpOverlapped será NULL e GetLastError retornará ERROR_ABANDONED_WAIT_0.

Windows Server 2003 e Windows XP: Fechar o identificador da porta de conclusão enquanto uma chamada estiver pendente não resultará no comportamento declarado anteriormente. A função continuará a aguardar até que uma entrada seja removida da porta ou até que ocorra um tempo limite, se especificado como um valor diferente de INFINITE.

Se a função GetQueuedCompletionStatus for bem-sucedida, ela removerá a fila de um pacote de conclusão para uma operação de E/S bem-sucedida da porta de conclusão e armazenará informações nas variáveis apontadas pelos seguintes parâmetros: lpNumberOfBytes, lpCompletionKey e lpOverlapped. Após a falha (o valor retornado é FALSE), esses mesmos parâmetros podem conter combinações de valores específicas da seguinte maneira:

  • Se *lpOverlapped for NULL, a função não removerá um pacote de conclusão da porta de conclusão. Nesse caso, a função não armazena informações nas variáveis apontadas pelos parâmetros lpNumberOfBytes e lpCompletionKey e seus valores são indeterminados.
  • Se *lpOverlapped não for NULL e a função remover um pacote de conclusão para uma operação de E/S com falha da porta de conclusão, a função armazenará informações sobre a operação com falha nas variáveis apontadas por lpNumberOfBytes, lpCompletionKey e lpOverlapped. Para obter informações de erro estendidas, chame GetLastError.
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.

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

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

Requisitos

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

Confira também

ConnectNamedPipe

Createiocompletionport

Deviceiocontrol

Funções de gerenciamento de arquivos

Funções

GetQueuedCompletionStatusEx

Portas de conclusão de E/S

LockFileEx

Tópicos de visão geral

PostQueuedCompletionStatus

ReadFile

TransactNamedPipe

Usando os cabeçalhos do Windows

Waitcommevent

WriteFile