Macro WSAAsyncGetHostByAddr (wsipv6ok.h)

Artigo
03/13/2024

A função WSAAsyncGetHostByAddr recupera de forma assíncrona as informações do host que correspondem a um endereço.

Nota A função WSAAsyncGetHostByAddr não foi projetada para fornecer resolução paralela de vários endereços. Portanto, os aplicativos que emitem várias solicitações não devem esperar que elas sejam executadas simultaneamente. Como alternativa, os aplicativos podem iniciar outro thread e usar a função getnameinfo para resolve endereços de maneira independente de versão IP. Os desenvolvedores que criam aplicativos do Windows Sockets 2 são instados a usar a função getnameinfo para habilitar a transição suave para a compatibilidade IPv6.

Sintaxe

void WSAAsyncGetHostByAddr(
  [in]   a,
  [in]   b,
  [in]   c,
  [in]   d,
  [in]   e,
  [out]  f,
  [in]   g
);

Parâmetros

[in] a

Identificador da janela que receberá uma mensagem quando a solicitação assíncrona for concluída.

[in] b

Mensagem a ser recebida quando a solicitação assíncrona for concluída.

[in] c

Ponteiro para o endereço de rede do host. Os endereços de host são armazenados em ordem de byte de rede.

[in] d

Comprimento do endereço, em bytes.

[in] e

Tipo do endereço.

[out] f

Ponteiro para a área de dados para receber os dados do hostent . A área de dados deve ser maior do que o tamanho de uma estrutura de hostent porque a área de dados é usada pelo Windows Sockets para conter uma estrutura de hostent e todos os dados referenciados por membros da estrutura de hostent . É recomendável um buffer de bytes MAXGETHOSTSTRUCT.

[in] g

Tamanho da área de dados para o parâmetro buf , em bytes.

Retornar valor

Nenhum

Comentários

A função WSAAsyncGetHostByAddr é uma versão assíncrona de gethostbyaddr. Ele é usado para recuperar o nome do host e as informações de endereço que correspondem a um endereço de rede. O Windows Sockets inicia a operação e retorna ao chamador imediatamente, retornando um identificador de tarefa opaco e assíncrono que o aplicativo pode usar para identificar a operação. Quando a operação é concluída, os resultados (se houver) são copiados para o buffer fornecido pelo chamador e uma mensagem é enviada para a janela do aplicativo.

Quando a operação assíncrona é concluída, a janela do aplicativo indicada pelo parâmetro hWnd recebe a mensagem no parâmetro wMsg . O parâmetro wParam contém o identificador de tarefa assíncrono, conforme retornado pela chamada de função original. Os 16 bits altos de lParam contêm qualquer código de erro. O código de erro pode ser qualquer erro, conforme definido em Winsock2.h. Um código de erro zero indica a conclusão bem-sucedida da operação assíncrona.

Após a conclusão bem-sucedida, o buffer especificado para a chamada de função original contém uma estrutura de hostent . Para acessar os membros dessa estrutura, o endereço de buffer original é convertido em um ponteiro de estrutura de host e acessado conforme apropriado.

Se o código de erro for WSAENOBUFS, o tamanho do buffer especificado por buflen na chamada original era muito pequeno para conter todas as informações resultantes. Nesse caso, os 16 bits baixos de lParam contêm o tamanho do buffer necessário para fornecer todas as informações necessárias. Se o aplicativo decidir que os dados parciais são inadequados, ele poderá reemissar a chamada da função WSAAsyncGetHostByAddr com um buffer grande o suficiente para receber todas as informações desejadas (ou seja, não menor que os 16 bits baixos de lParam).

O buffer especificado para essa função é usado pelo Windows Sockets para construir uma estrutura junto com o conteúdo das áreas de dados referenciadas por membros da mesma estrutura de host. Para evitar o erro WSAENOBUFS , o aplicativo deve fornecer um buffer de pelo menos bytes MAXGETHOSTSTRUCT (conforme definido em Winsock2.h).

O código de erro e o comprimento do buffer devem ser extraídos do lParam usando as macros WSAGETASYNCERROR e WSAGETASYNCBUFLEN, definidas em Winsock2.h como:

#include <windows.h>

#define WSAGETASYNCBUFLEN(lParam)           LOWORD(lParam)
#define WSAGETASYNCERROR(lParam)            HIWORD(lParam)

O uso dessas macros maximizará a portabilidade do código-fonte para o aplicativo.

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]
Plataforma de Destino	Windows
Cabeçalho	wsipv6ok.h (inclua Winsock2.h, Winsock.h)
Biblioteca	Ws2_32.lib
DLL	Ws2_32.dll