Função GetOverlappedResultEx (ioapiset.h)

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 GetLastErrorretornará 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 será enfileirada ou o intervalo será 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 enfileirada.

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 baixa potência Estados. 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 enfileira 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 retorna e a rotina de conclusão ou a função APC não é executada.

Uma rotina de conclusão é enfileirada quando a função ReadFileEx ou WriteFileEx na qual foi especificada tiver sido 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, GetLastErrorretornará 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 não for 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 simultâneas sobrepostas 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

   
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

Confira também

CancelIo

ConnectNamedPipe

CreateEvent

Deviceiocontrol

Getlasterror

GetOverlappedResult

SOBREPOSTA

Entrada e saída sobrepostas

ReadFile

Funções de sincronização

TransactNamedPipe

Waitcommevent

WriteFile