Função GetHostNameW (winsock2.h)
A função GetHostNameW recupera o nome do host padrão para o computador local como uma cadeia de caracteres Unicode.
Sintaxe
int WSAAPI GetHostNameW(
[out] PWSTR name,
[in] int namelen
);
Parâmetros
[out] name
Um ponteiro para um buffer que recebe o nome do host local como uma cadeia de caracteres Unicode terminada em nulo.
[in] namelen
O comprimento, em caracteres largos, do buffer apontado pelo parâmetro name .
Valor retornado
Se nenhum erro ocorrer, GetHostNameW retornará zero. Caso contrário, ele retorna SOCKET_ERROR e um código de erro específico pode ser recuperado chamando WSAGetLastError.
| Código do erro | Significado |
|---|---|
| O parâmetro name é um ponteiro NULL ou não é uma parte válida do espaço de endereço do usuário. Esse erro também será retornado se o tamanho do buffer especificado pelo parâmetro namelen for muito pequeno para manter o nome completo do host. | |
| Uma chamada WSAStartup bem-sucedida deve ocorrer antes de usar essa função. | |
| O subsistema de rede falhou. |
Comentários
A função GetHostNameW retorna o nome do host local no buffer especificado pelo parâmetro name em Unicode (UTF-16). O nome do host é retornado como uma cadeia de caracteres Unicode terminada em nulo. A forma do nome do host depende do provedor de Soquetes do Windows, pode ser um nome de host simples ou pode ser um nome de domínio totalmente qualificado. No entanto, é garantido que o nome retornado será analisado com êxito por GetAddrInfoW.
Com o crescimento da Internet, há uma necessidade crescente de identificar nomes de host da Internet para outros idiomas não representados pelo conjunto de caracteres ASCII. Identificadores que facilitam essa necessidade e permitem que caracteres não ASCII (Unicode) sejam representados como cadeias de caracteres ASCII especiais (Punycode) são conhecidos como IDNs (Nomes de Domínio Internacionalizados). Um mecanismo chamado IDNA (Internationalizing Domain Names in Applications) é usado para lidar com IDNs de forma padrão. A função GetHostNameW não converte o nome do host local entre Punycode e Unicode. A função GetAddrInfoW dá suporte à análise de IDN (Nome de Domínio Internacionalizado) e executa a codificação e a conversão do Punycode/IDN.
Se a função GetHostNameW for usada em um recurso de cluster no Windows Server 2012 e a variável de ambiente CLUSTER_NETWORK_NAME for definida, o valor nessa variável de ambiente substituirá o nome do host real e será retornado. Em um recurso de cluster, a variável de ambiente CLUSTER_NETWORK_NAME contém o nome do cluster.
A função GetHostNameW consulta provedores de namespace para determinar o nome do host local usando o GUID SVCID_HOSTNAME definido no arquivo de cabeçalho Svgguid.h . Se nenhum provedor de namespace responder, a função GetHostNameW retornará o nome NetBIOS do computador local em Unicode.
O comprimento máximo, em caracteres largos, da cadeia de caracteres retornada no buffer apontado pelo parâmetro name depende do provedor de namespace, mas essa cadeia de caracteres deve ter 256 caracteres largos ou menos. Portanto, se um buffer de 256 caracteres largos for passado no parâmetro name e o parâmetro namelen for definido como 256, o tamanho do buffer sempre será adequado.
Windows Phone 8: essa função tem suporte para aplicativos da Windows Phone Store no Windows Phone 8 e posterior.
Windows 8.1 e Windows Server 2012 R2: essa função tem suporte para aplicativos da Windows Store em Windows 8.1, Windows Server 2012 R2 e posterior.
Requisitos
| Cliente mínimo com suporte | Windows 8.1, Windows 8 [aplicativos da área de trabalho | Aplicativos UWP] |
| Servidor mínimo com suporte | Windows Server 2012 [aplicativos da área de trabalho | Aplicativos UWP] |
| Plataforma de Destino | Windows |
| Cabeçalho | winsock2.h |
| Biblioteca | Ws2_32.lib |
| DLL | Ws2_32.dll |