Função gethostname (winsock2.h)

  • Artigo

A função gethostname recupera o nome do host padrão para o computador local.

Sintaxe

int WSAAPI gethostname(
  [out] char *name,
  [in]  int  namelen
);

Parâmetros

[out] name

Um ponteiro para um buffer que recebe o nome do host local.

[in] namelen

O comprimento, em bytes, do buffer apontado pelo parâmetro name .

Retornar valor

Se nenhum erro ocorrer, gethostname retornará zero. Caso contrário, ele retornará SOCKET_ERROR e um código de erro específico poderá ser recuperado chamando WSAGetLastError.

Código do erro Significado
WSAEFAULT
 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 conter o nome completo do host.
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.

Comentários

A função gethostname retorna o nome do host local para o buffer especificado pelo parâmetro name . O nome do host é retornado como uma cadeia de caracteres terminada em nulo. A forma do nome do host depende do provedor do Windows Sockets, 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 gethostbyname e WSAAsyncGetHostByName.

O comprimento máximo do nome retornado no buffer apontado pelo parâmetro name depende do provedor de namespace.

Se a função gethostname for usada em um recurso de cluster no Windows Server 2008, Windows Server 2003 ou Windows 2000 Server 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 gethostname consulta provedores de namespace para determinar o nome do host local usando o GUID do SVCID_HOSTNAME definido no arquivo de cabeçalho Svgguid.h . Se nenhum provedor de namespace responder, a função gethostname retornará o nome NetBIOS do computador local.

O comprimento máximo, em bytes, 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 bytes ou menos. Portanto, se um buffer de 256 bytes for passado no parâmetro name e o parâmetro namelen for definido como 256, o tamanho do buffer sempre será adequado.

Nota Se nenhum nome de host local tiver sido configurado, gethostname deverá ter êxito e retornar um nome de host de token que gethostbyname ou WSAAsyncGetHostByName possa resolve.
 

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 posteriores.

Requisitos

Requisito Valor
Cliente mínimo com suporte Windows 8.1, Windows Vista [aplicativos da área de trabalho | Aplicativos UWP]
Servidor mínimo com suporte Windows Server 2003 [aplicativos da área de trabalho | Aplicativos UWP]
Plataforma de Destino Windows
Cabeçalho winsock2.h (inclua Winsock2.h)
Biblioteca Ws2_32.lib
DLL Ws2_32.dll

Confira também

GetAddrInfoW

WSAAsyncGetHostByName

Funções Winsock

Referência de Winsock

Gethostbyname