Função GetOverlappedResultEx (ioapiset.h)

Artigo
03/09/2023

Recupera os resultados de uma operação sobreposta no arquivo especificado, pipe nomeado ou dispositivo de comunicações dentro do intervalo de tempo limite especificado. O thread de chamada pode executar uma espera alertável.

Sintaxe

BOOL GetOverlappedResultEx(
  [in]  HANDLE       hFile,
  [in]  LPOVERLAPPED lpOverlapped,
  [out] LPDWORD      lpNumberOfBytesTransferred,
  [in]  DWORD        dwMilliseconds,
  [in]  BOOL         bAlertable
);

Parâmetros

[in] hFile

Um identificador para o arquivo, pipe nomeado ou dispositivo de comunicação. Esse é o mesmo identificador especificado quando a operação sobreposta foi iniciada por uma chamada para a função ReadFile, WriteFile, ConnectNamedPipe, TransactNamedPipe, DeviceIoControl ou WaitCommEvent .

[in] lpOverlapped

Um ponteiro para uma estrutura OVERLAPPED que foi especificada quando a operação sobreposta foi iniciada.

[out] lpNumberOfBytesTransferred

Um ponteiro para uma variável que recebe o número de bytes que foram realmente transferidos por uma operação de leitura ou gravação. Para uma operação TransactNamedPipe , esse é o número de bytes que foram lidos do pipe. Para uma operação DeviceIoControl , esse é o número de bytes de dados de saída retornados pelo driver do dispositivo. Para uma operação ConnectNamedPipe ou WaitCommEvent , esse valor é indefinido.

[in] dwMilliseconds

O intervalo de tempo limite em milissegundos.

Se dwMilliseconds for zero e a operação ainda estiver em andamento, a função retornará imediatamente e a função GetLastError retornará ERROR_IO_INCOMPLETE.

Se dwMilliseconds não for zero e a operação ainda estiver em andamento, a função aguardará até que o objeto seja sinalizado, uma rotina de conclusão de E/S ou APC esteja na fila ou o intervalo decorrido antes de retornar. Use GetLastError para obter informações de erro estendidas.

Se dwMilliseconds for INFINITE, a função retornará somente quando o objeto for sinalizado ou uma rotina de conclusão de E/S ou APC estiver na fila.

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] bAlertable

Se esse parâmetro for TRUE e o thread de chamada estiver no estado de espera, a função retornará quando o sistema enfileirar uma rotina de conclusão de E/S ou APC. Em seguida, o thread de chamada executa a rotina ou a função. Caso contrário, a função não retornará e a rotina de conclusão ou a função APC não será executada.

Uma rotina de conclusão é enfileirada quando a função ReadFileEx ou WriteFileEx na qual foi especificada foi concluída. A função retorna e a rotina de conclusão é chamada somente se bAlertable for TRUE e o thread de chamada for o thread que iniciou a operação de leitura ou gravação. Um APC é enfileirado quando você chama QueueUserAPC.

Valor retornado

Se a função for bem-sucedida, o valor retornado será diferente de zero.

Se a função falhar, o valor retornado será zero. Para obter informações de erro estendidas, chame GetLastError. Os códigos de erro comuns incluem o seguinte:

Se dwMilliseconds for zero e a operação ainda estiver em andamento, GetLastError retornará ERROR_IO_INCOMPLETE.
Se dwMilliseconds não for zero e uma rotina de conclusão de E/S ou APC estiver na fila, GetLastError retornará WAIT_IO_COMPLETION.
Se dwMilliseconds for diferente de zero e o intervalo de tempo limite especificado decorrido, GetLastError retornará WAIT_TIMEOUT.

Comentários

A função GetOverlappedResultEx difere de GetOverlappedResult das seguintes maneiras: o parâmetro dwMilliseconds pode especificar um intervalo de tempo limite para a operação e o parâmetro bAlertable pode especificar que o thread de chamada deve executar uma espera alertável.

Os resultados relatados pela função GetOverlappedResultEx são os da última operação sobreposta do identificador especificado à qual a estrutura OVERLAPPED especificada foi fornecida e para a qual os resultados da operação estavam pendentes. Uma operação pendente é indicada quando a função que iniciou a operação retorna FALSE e a função GetLastError retorna ERROR_IO_PENDING. Quando uma operação de E/S está pendente, a função que iniciou a operação redefine o membro hEvent da estrutura OVERLAPPED para o estado não atribuído. Em seguida, quando a operação pendente for concluída, o sistema definirá o objeto de evento como o estado sinalizado.

Especifique um objeto de evento de redefinição manual na estrutura OVERLAPPED . Se um objeto de evento de redefinição automática for usado, o identificador de evento não deverá ser especificado em nenhuma outra operação de espera no intervalo entre iniciar a operação sobreposta e a chamada para GetOverlappedResultEx. Por exemplo, o objeto de evento às vezes é especificado em uma das funções de espera para aguardar a conclusão da operação. Quando a função de espera retorna, o sistema define o estado de um evento de redefinição automática como não atribuído e uma chamada subsequente para GetOverlappedResultEx com o parâmetro dwMilliseconds definido como INFINITE faz com que a função seja bloqueada indefinidamente.

Se o membro hEvent da estrutura OVERLAPPED for NULL, o sistema usará o estado do identificador hFile para sinalizar quando a operação tiver sido concluída. O uso de identificadores de arquivo, pipe nomeado ou comunicações-dispositivo para essa finalidade é desencorajado. É mais seguro usar um objeto de evento devido à confusão que pode ocorrer quando várias operações sobrepostas simultâneas são executadas no mesmo arquivo, pipe nomeado ou dispositivo de comunicação. Nessa situação, não há como saber qual operação fez com que o estado do objeto fosse sinalizado.

Requisitos

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