Função WSAGetOverlappedResult (winsock2.h)

Artigo
08/27/2023

A função WSAGetOverlappedResult recupera os resultados de uma operação sobreposta no soquete especificado.

Sintaxe

BOOL WSAAPI WSAGetOverlappedResult(
  [in]  SOCKET          s,
  [in]  LPWSAOVERLAPPED lpOverlapped,
  [out] LPDWORD         lpcbTransfer,
  [in]  BOOL            fWait,
  [out] LPDWORD         lpdwFlags
);

Parâmetros

[in] s

Um descritor que identifica o soquete.

Esse é o mesmo soquete especificado quando a operação sobreposta foi iniciada por uma chamada para qualquer uma das funções Winsock que dão suporte a operações sobrepostas. Essas funções incluem AcceptEx, ConnectEx, DisconnectEx, TransmitFile, TransmitPackets, WSARecv, WSARecvFrom, LPFN_WSARECVMSG (WSARecvMsg),WSASend, WSASendMsg, WSASendTo e WSAIoctl.

[in] lpOverlapped

Um ponteiro para uma estrutura WSAOVERLAPPED que foi especificada quando a operação sobreposta foi iniciada. Esse parâmetro não deve ser um ponteiro NULL .

[out] lpcbTransfer

Um ponteiro para uma variável de 32 bits que recebe o número de bytes que foram realmente transferidos por uma operação de envio ou recebimento ou pela função WSAIoctl . Esse parâmetro não deve ser um ponteiro NULL .

[in] fWait

Um sinalizador que especifica se a função deve aguardar a conclusão da operação sobreposta pendente. Se TRUE, a função não retornará até que a operação seja concluída. Se FALSE e a operação ainda estiverem pendentes, a função retornará FALSE e a função WSAGetLastError retornará WSA_IO_INCOMPLETE. O parâmetro fWait só poderá ser definido como TRUE se a operação sobreposta tiver selecionado a notificação de conclusão baseada em evento.

[out] lpdwFlags

Um ponteiro para uma variável de 32 bits que receberá um ou mais sinalizadores que complementam o status de conclusão. Se a operação sobreposta tiver sido iniciada por meio de WSARecv ou WSARecvFrom, esse parâmetro conterá o valor de resultados para o parâmetro lpFlags . Esse parâmetro não deve ser um ponteiro NULL .

Retornar valor

Se WSAGetOverlappedResult for bem-sucedido, o valor retornado será TRUE. Isso significa que a operação sobreposta foi concluída com êxito e que o valor apontado por lpcbTransfer foi atualizado.

Se WSAGetOverlappedResult retornar FALSE, isso significa que a operação sobreposta não foi concluída, a operação sobreposta concluída, mas com erros, ou a conclusão da operação sobreposta status não pôde ser determinada devido a erros em um ou mais parâmetros para WSAGetOverlappedResult. Em caso de falha, o valor apontado por lpcbTransfer não será atualizado. Use WSAGetLastError para determinar a causa da falha (seja pela função WSAGetOverlappedResult ou pela operação sobreposta associada).

Código do erro	Significado
WSANOTINITIALISED	Uma chamada WSAStartup bem-sucedida deve ocorrer antes de usar essa função.
WSAENETDOWN	O subsistema de rede falhou.
WSAENOTSOCK	O descritor não é um soquete.
WSA_INVALID_HANDLE	O parâmetro hEvent da estrutura WSAOVERLAPPED não contém um identificador de objeto de evento válido.
WSA_INVALID_PARAMETER	Um dos parâmetros é inaceitável.
WSA_IO_INCOMPLETE	O parâmetro fWait é FALSE e a operação de E/S ainda não foi concluída.
WSAEFAULT	Um ou mais dos parâmetros lpOverlapped, lpcbTransfer ou lpdwFlags não estão em uma parte válida do espaço de endereço do usuário. Esse erro será retornado se o parâmetro lpOverlapped, lpcbTransfer ou lpdwFlags for um ponteiro NULL no Windows Server 2003 e anterior.

Comentários

A função WSAGetOverlappedResult relata os resultados da operação sobreposta especificada no parâmetro lpOverlapped para o soquete especificado no parâmetro s . A função WSAGetOverlappedResult é passada pelo descritor de soquete e pela estrutura WSAOVERLAPPED que foi especificada quando a função sobreposta foi chamada. Uma operação pendente é indicada quando a função que iniciou a operação retorna FALSE e a função WSAGetLastError retorna WSA_IO_PENDING. Quando uma operação de E/S como WSARecv está pendente, a função que iniciou a operação redefine o membro hEvent da estrutura WSAOVERLAPPED 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 fWait for TRUE, WSAGetOverlappedResult determinará se a operação pendente foi concluída aguardando o objeto de evento estar no estado sinalizado. Um cliente pode definir o parâmetro fWait como TRUE, mas somente se ele selecionou a notificação de conclusão baseada em evento quando a operação de E/S foi solicitada. Se outra forma de notificação tiver sido selecionada, o uso do parâmetro hEvent da estrutura WSAOVERLAPPED será diferente e definir fWait como TRUE causará resultados imprevisíveis.

Se a função WSAGetOverlappedResult for chamada com o parâmetro lpOverlapped, lpcbTransfer ou lpdwFlags definido como um ponteiro NULL no Windows Vista, isso resultará em uma violação de acesso. Se a função WSAGetOverlappedResult for chamada com o parâmetro lpOverlapped, lpcbTransfer ou lpdwFlags definido como um ponteiro NULL no Windows Server 2003 e anterior, isso resultará no retorno do código de erro WSAEFAULT .

Nota Todas as E/S são canceladas quando um thread é encerrado. Para soquetes sobrepostos, as operações assíncronas pendentes podem falhar se o thread for fechado antes da conclusão das operações. Consulte ExitThread para obter mais informações.

Windows Phone 8: essa função tem suporte para aplicativos da Windows Phone Store no Windows Phone 8 e posterior.

Windows 8.1 e Windows Server 2012 R2: essa função tem suporte para aplicativos da Windows Store em Windows 8.1, Windows Server 2012 R2 e posteriores.

Requisitos

Requisito	Valor
Cliente mínimo com suporte	Windows 8.1, Windows Vista [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	winsock2.h
Biblioteca	Ws2_32.lib
DLL	Ws2_32.dll