Função GetOverlappedResult (ioapiset.h)

Recupera os resultados de uma operação sobreposta no arquivo especificado, pipe nomeado ou dispositivo de comunicações. Para especificar um intervalo de tempo limite ou aguardar em um thread alertável, use GetOverlappedResultEx.

Sintaxe

BOOL GetOverlappedResult(
  [in]  HANDLE       hFile,
  [in]  LPOVERLAPPED lpOverlapped,
  [out] LPDWORD      lpNumberOfBytesTransferred,
  [in]  BOOL         bWait
);

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 qualquer uma das seguintes funções:

• ReadFile
• WriteFile
• ConnectNamedPipe
• TransactNamedPipe
• DeviceIoControl
• WaitCommEvent
• ReadDirectoryChangesW
• LockFileEx

[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] bWait

Se esse parâmetro for TRUE e o membro Interno da estrutura lpOverlapped for STATUS_PENDING, a função não retornará até que a operação seja concluída. Se esse parâmetro for FALSE e a operação ainda estiver pendente, a função retornará FALSE e a função GetLastErrorretornará ERROR_IO_INCOMPLETE.

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.

Comentários

Os resultados relatados pela função GetOverlappedResult 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.

Se o parâmetro bWait for TRUE, GetOverlappedResult determinará se a operação pendente foi concluída aguardando o objeto de evento estar no estado sinalizado.

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.

Exemplos

Para obter um exemplo que usa GetOverlappedResult, consulte Testando para o fim de um arquivo

Requisitos

Confira também

CancelIo, CreateEvent, GetOverlappedResultEx, OVERLAPPED, Entrada e saída sobrepostas, funções de sincronização