Função GetAddressByNameA (nspapi.h)

  • Artigo

[GetAddressByName não está mais disponível para uso a partir do Windows Sockets 2. Em vez disso, use as funções detalhadas em Resolução de Nomes Independentes de Protocolo.]

A função GetAddressByName consulta um namespace ou um conjunto de namespaces padrão para recuperar informações de endereço de rede para um serviço de rede especificado. Esse processo é conhecido como resolução de nome de serviço. Um serviço de rede também pode usar a função para obter informações de endereço local que ele pode usar com a função de associação .

Sintaxe

INT GetAddressByNameA(
  [in]           DWORD                dwNameSpace,
  [in]           LPGUID               lpServiceType,
  [in, optional] LPSTR                lpServiceName,
  [in, optional] LPINT                lpiProtocols,
  [in]           DWORD                dwResolution,
  [in, optional] LPSERVICE_ASYNC_INFO lpServiceAsyncInfo,
  [out]          LPVOID               lpCsaddrBuffer,
  [in, out]      LPDWORD              lpdwBufferLength,
  [in, out]      LPSTR                lpAliasBuffer,
  [in, out]      LPDWORD              lpdwAliasBufferLength
);

Parâmetros

[in] dwNameSpace

O namespace ou o conjunto de namespaces padrão que o sistema operacional deve consultar para obter informações de endereço de rede.

Use uma das seguintes constantes para especificar um namespace.

Valor Significado
NS_DEFAULT
 Um conjunto de namespaces padrão. A função consulta cada namespace dentro desse conjunto. O conjunto de namespaces padrão normalmente inclui todos os namespaces instalados no sistema. No entanto, os administradores do sistema podem excluir namespaces específicos do conjunto. Esse é o valor que a maioria dos aplicativos deve usar para dwNameSpace.
NS_DNS
 O DNS (Sistema de Nomes de Domínio) usado na Internet para resolução de nomes de host.
NS_NETBT
 A camada NetBIOS sobre TCP/IP. Todos os sistemas operacionais registram seus nomes de computador com NetBIOS. Esse namespace é usado para converter um nome de computador em um endereço IP que usa esse registro. Observe que NS_NETBT pode acessar um servidor WINS para executar a resolução.
NS_SAP
 O Protocolo de Publicidade do Serviço NetWare. Isso pode acessar a associação netware, se apropriado. NS_SAP é um namespace dinâmico que permite o registro de serviços.
NS_TCPIP_HOSTS
 Valor de pesquisa no <arquivo systemroot>\system32\drivers\etc\hosts.
NS_TCPIP_LOCAL
 Mecanismos locais de resolução de nomes TCP/IP, incluindo comparações com o nome do host local e pesquisa nomes de host e endereços IP no cache de mapeamentos de host para endereço IP.
 

A maioria das chamadas para GetAddressByName deve usar o valor especial NS_DEFAULT. Isso permite que um cliente se dê bem sem conhecimento de quais namespaces estão disponíveis em um trabalho na Internet. O administrador do sistema determina o acesso ao namespace. Os namespaces podem ir e vir sem que o cliente precise estar ciente das alterações.

[in] lpServiceType

Um ponteiro para um GUID (identificador global exclusivo) que especifica o tipo do serviço de rede. O arquivo de cabeçalho Svcguid.h inclui definições de vários tipos de serviço GUID e macros para trabalhar com eles.

O arquivo de cabeçalho Svcguid.h não é incluído automaticamente pelo arquivo de cabeçalho Winsock2.h.

[in, optional] lpServiceName

Um ponteiro para uma cadeia de caracteres terminada em zero que representa exclusivamente o nome do serviço. Por exemplo, "MY SNA SERVER".

Definir lpServiceName como NULL é o equivalente a definir dwResolution como RES_SERVICE. A função opera em seu segundo modo, obtendo o endereço local ao qual um serviço do tipo especificado deve ser associado. A função armazena o endereço local dentro do membro LocalAddr das estruturas de CSADDR_INFO armazenadas em *lpCsaddrBuffer.

Se dwResolution estiver definido como RES_SERVICE, a função ignorará o parâmetro lpServiceName .

Se dwNameSpace estiver definido como NS_DNS, *lpServiceName será o nome do host.

[in, optional] lpiProtocols

Um ponteiro para uma matriz terminada em zero de identificadores de protocolo. A função restringe uma tentativa de resolução de nomes para provedores de namespace que oferecem esses protocolos. Isso permite que o chamador limite o escopo da pesquisa.

Se lpiProtocols estiver definido como NULL, a função recuperará informações sobre todos os protocolos disponíveis.

[in] dwResolution

Um conjunto de sinalizadores de bits que especificam aspectos do processo de resolução de nomes de serviço. Os sinalizadores de bit a seguir são definidos.

Valor Significado
RES_SERVICE
 Se definida, a função recuperará o endereço ao qual um serviço do tipo especificado deve ser associado. Isso é o equivalente a definir o parâmetro lpServiceName como NULL.

Se esse sinalizador estiver claro, ocorrerá a resolução normal de nomes.
RES_FIND_MULTIPLE
 Se esse sinalizador estiver definido, o sistema operacional executará uma pesquisa extensiva de todos os namespaces para o serviço. Ele solicita que todos os namespaces apropriados resolve o nome do serviço. Se esse sinalizador estiver claro, o sistema operacional deixará de procurar endereços de serviço assim que um for encontrado.
RES_SOFT_SEARCH
 Esse sinalizador será válido se o namespace der suporte a vários níveis de pesquisa.

Se esse sinalizador for válido e definido, o sistema operacional executará uma pesquisa simples e rápida do namespace. Isso será útil se um aplicativo precisar apenas obter endereços fáceis de localizar para o serviço.

Se esse sinalizador for válido e claro, o sistema operacional executará uma pesquisa mais abrangente do namespace.

[in, optional] lpServiceAsyncInfo

Reservado para uso futuro; deve ser definido como NULL.

[out] lpCsaddrBuffer

Um ponteiro para um buffer para receber uma ou mais estruturas de dados CSADDR_INFO. O número de estruturas gravadas no buffer depende da quantidade de informações encontradas na tentativa de resolução. Você deve assumir que várias estruturas serão escritas, embora em muitos casos haja apenas uma.

[in, out] lpdwBufferLength

Um ponteiro para uma variável que, após a entrada, especifica o tamanho, em bytes, do buffer apontado por lpCsaddrBuffer.

Após a saída, essa variável contém o número total de bytes necessários para armazenar a matriz de estruturas CSADDR_INFO . Se esse valor for menor ou igual ao valor de entrada de *lpdwBufferLength e a função for bem-sucedida, esse será o número de bytes realmente armazenados no buffer. Se esse valor for maior que o valor de entrada de *lpdwBufferLength, o buffer será muito pequeno e o valor de saída de *lpdwBufferLength será o tamanho mínimo necessário do buffer.

[in, out] lpAliasBuffer

Um ponteiro para um buffer para receber informações de alias para o serviço de rede.

Se um namespace der suporte a aliases, a função armazenará uma matriz de cadeias de caracteres de nome com terminação zero no buffer apontado por lpAliasBuffer. Há um terminador zero duplo no final da lista. O nome na matriz é o nome principal do serviço. Os nomes a seguir são aliases. Um exemplo de um namespace que dá suporte a aliases é DNS.

Se um namespace não der suporte a aliases, ele armazenará um terminador zero duplo no buffer.

Esse parâmetro é opcional e pode ser definido como NULL.

[in, out] lpdwAliasBufferLength

Um ponteiro para uma variável que, após a entrada, especifica o tamanho, em elementos (caracteres), do buffer apontado por lpAliasBuffer.

Após a saída, essa variável contém o número total de elementos (caracteres) necessários para armazenar a matriz de cadeias de caracteres de nome. Se esse valor for menor ou igual ao valor de entrada de *lpdwAliasBufferLength e a função for bem-sucedida, esse será o número de elementos realmente armazenados no buffer. Se esse valor for maior que o valor de entrada de *lpdwAliasBufferLength, o buffer será muito pequeno e o valor de saída de *lpdwAliasBufferLength será o tamanho mínimo necessário do buffer.

Se lpAliasBuffer for NULL, lpdwAliasBufferLength não tem sentido e também poderá ser NULL.

Retornar valor

Se a função for bem-sucedida, o valor retornado será o número de estruturas de dados CSADDR_INFO gravadas no buffer apontado por lpCsaddrBuffer.

Se a função falhar, o valor retornado será SOCKET_ERROR( –1). Para obter informações de erro estendidas, chame GetLastError, que retorna o seguinte valor de erro estendido.

Código do erro Significado
ERROR_INSUFFICIENT_BUFFER
 O buffer apontado por lpCsaddrBuffer era muito pequeno para receber todas as estruturas de CSADDR_INFO relevantes. Chame a função com um buffer pelo menos tão grande quanto o valor retornado em *lpdwBufferLength.

Comentários

Essa função é uma versão mais poderosa da função gethostbyname . A função GetAddressByName funciona com vários serviços de nome.

Nota A função gethostbyname foi preterida pela introdução da função getaddrinfo . Os desenvolvedores que criam aplicativos do Windows Sockets 2 são instados a usar a função getaddrinfo em vez de gethostbyname.
 

A função GetAddressByName permite que um cliente obtenha um endereço do Windows Sockets para um serviço de rede. O cliente especifica o serviço de interesse por seu tipo de serviço e nome de serviço.

Muitos serviços de nome dão suporte a um prefixo ou sufixo padrão que o provedor de serviços de nome considera ao resolver nomes de serviço. Por exemplo, no namespace DNS, se um domínio for chamado "nt.microsoft.com" e "ftp millikan" for fornecido como entrada, o software DNS não conseguirá resolve "millikan", mas resolverá com êxito "millikan.nt.microsoft.com".

Observe que a função GetAddressByName pode pesquisar um endereço de serviço de duas maneiras: dentro de um namespace específico ou dentro de um conjunto de namespaces padrão. Usando um namespace padrão, um administrador pode especificar que determinados namespaces serão pesquisados para endereços de serviço somente se especificados por nome. Um administrador ou namespace — o programa de instalação também pode controlar a ordenação de pesquisas de namespace.

Observação

O cabeçalho nspapi.h define GetAddressByName como um alias que seleciona automaticamente a versão ANSI ou Unicode dessa função com base na definição da constante de pré-processador UNICODE. Misturar o uso do alias neutro de codificação com código que não seja neutro em codificação pode levar a incompatibilidades que resultam em erros de compilação ou de runtime. Para obter mais informações, consulte Convenções para protótipos de função.

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 nspapi.h
Biblioteca Mswsock.lib
DLL Mswsock.dll

Confira também

CSADDR_INFO

Funções Winsock

Referência de Winsock

Getaddrinfo

Gethostbyname