Função GetAddressByNameA (nspapi.h)
[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.
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.
[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 |
|---|---|
|
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.
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 |