Função de retorno de chamada LPWSPGETOVERLAPPEDRESULT (ws2spi.h)

Artigo
08/28/2023

A função LPWSPGetOverlappedResult retorna os resultados de uma operação sobreposta no soquete especificado.

Sintaxe

LPWSPGETOVERLAPPEDRESULT Lpwspgetoverlappedresult;

BOOL Lpwspgetoverlappedresult(
  [in]  SOCKET s,
  [in]  LPWSAOVERLAPPED lpOverlapped,
  [out] LPDWORD lpcbTransfer,
  [in]  BOOL fWait,
  [out] LPDWORD lpdwFlags,
  [out] LPINT lpErrno
)
{...}

Parâmetros

[in] s

Identifica o soquete. Esse é o mesmo soquete especificado quando a operação sobreposta foi iniciada por uma chamada para LPWSPRecv, LPWSPRecvFrom, LPWSPSend, LPWSPSendTo ou LPWSPIoctl.

[in] lpOverlapped

Ponteiro para uma estrutura WSAOverlapped que foi especificada quando a operação sobreposta foi iniciada.

[out] lpcbTransfer

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 por LPWSPIoctl.

[in] fWait

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 estiver pendente, a função retornará FALSE e lpErrno será 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

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 LPWSPRecv ou LPWSPRecvFrom, esse parâmetro conterá o valor de resultados para o parâmetro lpFlags .

[out] lpErrno

Ponteiro para o código de erro.

Retornar valor

Se LPWSPGetOverlappedResult for bem-sucedido, o valor retornado será TRUE. Isso significa que a operação sobreposta foi concluída com êxito e o valor apontado por lpcbTransfer foi atualizado. Se LPWSPGetOverlappedResult retornar FALSE, isso significa que a operação sobreposta não foi concluída ou a operação sobreposta concluída, mas com erros ou status de conclusão não pôde ser determinada devido a erros em um ou mais parâmetros para LPWSPGetOverlappedResult. Em caso de falha, o valor apontado por lpcbTransfer não será atualizado. O parâmetro lpErrno indica a causa da falha (de LPWSPGetOverlappedResult ou da operação sobreposta associada).

Código do Erro	Significado
WSAENETDOWN	O subsistema de rede falhou.
WSAENOTSOCK	O descritor não é um soquete.
WSA_INVALID_HANDLE	O membro hEvent da estrutura WSAOverlapped não contém um identificador de objeto de evento válido.
WSAEINVAL	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.

Comentários

Os resultados relatados pela função LPWSPGetOverlappedResult são os da última operação sobreposta do soquete especificado à qual a estrutura WSAOverlapped 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 SOCKET_ERROR e o lpErrno é WSA_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 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, LPWSPGetOverlappedResult determinará se a operação pendente foi concluída bloqueando e aguardando que o objeto de evento esteja no estado sinalizado. Um cliente poderá definir o parâmetro fWait como TRUE 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 membro hEvent da estrutura WSAOverlapped será diferente e definir fWait como TRUE causará resultados imprevisíveis.

Observação

Todas as E/S iniciadas por um determinado thread são canceladas quando esse 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.

Interação com WPUCompleteOverlappedRequest

O comportamento de WPUCompleteOverlappedRequest coloca algumas restrições sobre como um provedor de serviços implementa LPWSPGetOverlappedResult , pois apenas os membros Offset e OffsetHigh da estrutura WSAOverlapped são controlados exclusivamente pelo provedor de serviços, embora três valores (contagem de bytes, sinalizadores e erro) precisem ser recuperados da estrutura por LPWSPGetOverlappedResult. Um provedor de serviços pode fazer isso da maneira que escolher, desde que interaja com o comportamento de WPUCompleteOverlappedRequest corretamente. A descrição a seguir apresenta uma implementação típica:

No início do processamento sobreposto, o provedor de serviços define Interno como WSS_OPERATION_IN_PROGRESS.

Quando a operação de E/S é concluída, o provedor define OffsetHigh como o código de erro do Windows Sockets 2 resultante da operação, define Deslocamento para os sinalizadores resultantes da operação de E/S e chama WPUCompleteOverlappedRequest, passando a contagem de bytes de transferência como um dos parâmetros. WPUCompleteOverlappedRequest eventualmente define InternalHigh como a contagem de bytes de transferência e, em seguida, define Interno como um valor diferente de WSS_OPERATION_IN_PROGRESS.

Quando LPWSPGetOverlappedResult é chamado, o provedor de serviços verifica Interno. Se for WSS_OPERATION_IN_PROGRESS, o provedor aguardará o identificador de evento no membro hEvent ou retornará um erro, com base na configuração do sinalizador fWait de LPWSPGetOverlappedResult. Se não estiver em andamento ou após a conclusão da espera, o provedor retornará os valores de InternalHigh, OffsetHigh e Offset como a contagem de transferências, o código de erro do resultado da operação e os sinalizadores, respectivamente.

Requisitos

Requisito	Valor
Cliente mínimo com suporte	Windows 2000 Professional [somente aplicativos da área de trabalho]
Servidor mínimo com suporte	Windows 2000 Server [somente aplicativos da área de trabalho]
Cabeçalho	ws2spi.h