Função GetAddressByNameW (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 Protocol-Independentde Resolução de Nomes .]
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 associar.
Sintaxe
INT GetAddressByNameW(
[in] DWORD dwNameSpace,
[in] LPGUID lpServiceType,
[in, optional] LPWSTR lpServiceName,
[in, optional] LPINT lpiProtocols,
[in] DWORD dwResolution,
[in, optional] LPSERVICE_ASYNC_INFO lpServiceAsyncInfo,
[out] LPVOID lpCsaddrBuffer,
[in, out] LPDWORD lpdwBufferLength,
[in, out] LPWSTR 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 obtenha informações sobre 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 com término zero que representa exclusivamente o nome do serviço. Por exemplo, "MY SNA SERVER".
Definir lpServiceName para NULL é o equivalente à configuração 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 no localAddr membro das estruturas de CSADDR_INFO armazenadas em *lpCsaddrBuffer.
Se dwResolution estiver definida 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 de identificadores de protocolo com término zero. A função restringe uma tentativa de resolução de nomes a 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 de CSADDR_INFO. Se esse valor for menor ou igual ao valor de entrada de *lpdwBufferLengthe 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 era muito pequeno e o valor de saída de *lpdwBufferLength é o tamanho mínimo do buffer necessário.
[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 término 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 era muito pequeno e o valor de saída de *lpdwAliasBufferLength é o tamanho mínimo do buffer necessário.
Se lpAliasBuffer for NULL, lpdwAliasBufferLength não tiver sentido e também poderá ser NULL.
Valor de retorno
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 de 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. |
Observações
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 é chamado de "nt.microsoft.com" e "ftp millikan" é fornecido como entrada, o software DNS falha ao resolver "millikan", mas resolve com êxito "millikan.nt.microsoft.com".
Observe que a função GetAddressByName pode procurar 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 por endereços de serviço somente se especificados pelo nome. Um administrador ou namespace — programa de instalação também pode controlar a ordenação de pesquisas de namespace.
Nota
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 do pré-processador UNICODE. A combinação do uso do alias neutro de codificação com código que não é neutro em codificação pode levar a incompatibilidades que resultam em erros de compilação ou de runtime. Para obter mais informações, consulte Conventions for Function Prototypes.
Requisitos
| Requisito | Valor |
|---|---|
| de cliente com suporte mínimo | Windows 2000 Professional [somente aplicativos da área de trabalho] |
| servidor com suporte mínimo | Windows 2000 Server [somente aplicativos da área de trabalho] |
| da Plataforma de Destino |
Windows |
| cabeçalho | nspapi.h |
| biblioteca | Mswsock.lib |
| de DLL |
Mswsock.dll |
Consulte também
do Winsock Functions
referência Winsock