Função WSAAsyncGetHostByAddr (winsock2.h)

Artigo
08/27/2023

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 da 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

HANDLE WSAAPI WSAAsyncGetHostByAddr(
  HWND       hWnd,
  u_int      wMsg,
  const char *addr,
  int        len,
  int        type,
  char       *buf,
  int        buflen
);

Parâmetros

hWnd

TBD

wMsg

TBD

addr

TBD

len

TBD

type

TBD

buf

TBD

buflen

TBD

Valor retornado

O valor retornado especifica se a operação assíncrona foi iniciada com êxito ou não. Isso não implica êxito ou falha da operação em si.

Se nenhum erro ocorrer, WSAAsyncGetHostByAddr retornará um valor diferente de zero do tipo HANDLE que é o identificador de tarefa assíncrona (não deve ser confundido com um HTASK do Windows) para a solicitação. Esse valor pode ser usado de duas maneiras. Ele pode ser usado para cancelar a operação usando WSACancelAsyncRequest ou pode ser usado para corresponder operações assíncronas e mensagens de conclusão examinando o parâmetro de mensagem wParam .

Se a operação assíncrona não puder ser iniciada, WSAAsyncGetHostByAddr retornará um valor zero e um número de erro específico poderá ser recuperado chamando WSAGetLastError.

Os códigos de erro a seguir podem ser definidos quando uma janela do aplicativo recebe uma mensagem. Conforme descrito acima, eles podem ser extraídos do lParam na mensagem de resposta usando a macro WSAGETASYNCERROR .

Código do erro	Significado
WSAENETDOWN	O subsistema de rede falhou.
WSAENOBUFS	Espaço em buffer insuficiente está disponível.
WSAEFAULT	O parâmetro addr ou buf não está em uma parte válida do espaço de endereço do processo.
WSAHOST_NOT_FOUND	Host de resposta autoritativa não encontrado.
WSATRY_AGAIN	Host não autenticativo não encontrado ou SERVERFAIL.
WSANO_RECOVERY	Erros não recuperáveis: FORMERR, REFUSED, NOTIMP.
WSANO_DATA	Nome válido, nenhum registro de dados do tipo solicitado.

Os erros a seguir podem ocorrer no momento da chamada de função e indicar que a operação assíncrona não pôde ser iniciada.

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.
WSAEINPROGRESS	Uma chamada de bloqueio do Windows Sockets 1.1 está em andamento ou o provedor de serviços ainda está processando uma função de retorno de chamada.
WSAEWOULDBLOCK	A operação assíncrona não pode ser agendada no momento devido a recursos ou outras restrições na implementação do Windows Sockets.

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, passando 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íncrona, 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 do buffer original é convertido em um ponteiro da estrutura do hostent 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á reemiter 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 hostent . 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


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	winsock2.h (incluem Winsock2.h, Winsock.h)
Biblioteca	Ws2_32.lib
DLL	Ws2_32.dll