macro gethostbyname (wsipv6ok.h)
A função gethostbyname recupera informações de host correspondentes a um nome de host de um banco de dados de host.
Sintaxe
void gethostbyname(
[in] a
);
Parâmetros
[in] a
Um ponteiro para o nome terminado em nulo do host para resolve.
Retornar valor
Nenhum
Comentários
A função gethostbyname retorna um ponteiro para uma estrutura de host — uma estrutura alocada pelo Windows Sockets. A estrutura de host contém os resultados de uma pesquisa bem-sucedida para o host especificado no parâmetro name .
Se o host especificado no parâmetro name tiver endereços IPv4 e IPv6, somente os endereços IPv4 serão retornados. A função gethostbyname só pode retornar endereços IPv4 para o parâmetro name . A função getaddrinfo e a estrutura addrinfo associada devem ser usadas se os endereços IPv6 para o host forem necessários ou se os endereços IPv4 e IPv6 para o host forem necessários.
Se o parâmetro name apontar para uma cadeia de caracteres ou nome vazio for NULL, a cadeia de caracteres retornada será a mesma que a cadeia de caracteres retornada por uma chamada de função gethostname bem-sucedida (o nome do host padrão para o computador local).
Se o parâmetro name contiver uma representação de cadeia de caracteres de um endereço IPv4 legal, o endereço IPv4 binário que representa a cadeia de caracteres será retornado na estrutura do hostent . O membro h_name da estrutura de host contém a representação de cadeia de caracteres do endereço IPv4 e o h_addr_list contém o endereço IPv4 binário. Se o parâmetro name contiver uma representação de cadeia de caracteres de um endereço IPv6 ou um endereço IPv4 ilegal, a função gethostbyname falhará e retornará WSANO_DATA.
A memória da estrutura de host retornada pela função gethostbyname é alocada internamente pela DLL winsock do armazenamento local do thread. Apenas uma única estrutura de hostent é alocada e usada, independentemente de quantas vezes as funções gethostbyaddr ou gethostbyname são chamadas no thread. A estrutura de host retornada deverá ser copiada para um buffer de aplicativo se chamadas adicionais forem feitas para as funções gethostbyname ou gethostbyaddr no mesmo thread. Caso contrário, o valor retornado será substituído por chamadas gethostbyname ou gethostbyaddr subsequentes no mesmo thread. A memória interna alocada para a estrutura de host retornada é liberada pela DLL winsock quando o thread é encerrado.
Um aplicativo não deve tentar liberar a memória usada pela estrutura de host retornada. O aplicativo nunca deve tentar modificar essa estrutura ou liberar nenhum de seus componentes. Além disso, apenas uma cópia dessa estrutura é alocada por thread, portanto, o aplicativo deve copiar todas as informações necessárias antes de emitir qualquer outra chamada de função para gethostbyname ou gethostbyaddr .
A função gethostbyname não pode usar uma cadeia de caracteres de endereço IP como um parâmetro passado para ele no nome e resolve-a para um nome de host. Essa solicitação é tratada exatamente como uma representação de cadeia de caracteres de um endereço IPv4 ou um nome de host desconhecido foi passado. Um aplicativo pode usar o inet_addr para converter uma cadeia de caracteres de endereço IPv4 em um endereço IPv4 binário e, em seguida, usar outra função, gethostbyaddr, para resolve o endereço IPv4 em um nome de host.
Código de exemplo
Os exemplos a seguir demonstram o uso da função gethostbyname .#include <winsock2.h>
#include <ws2tcpip.h>
#include <stdio.h>
#include <windows.h>
#pragma comment(lib, "ws2_32.lib")
int main(int argc, char **argv)
{
//-----------------------------------------
// Declare and initialize variables
WSADATA wsaData;
int iResult;
DWORD dwError;
int i = 0;
struct hostent *remoteHost;
char *host_name;
struct in_addr addr;
char **pAlias;
// Validate the parameters
if (argc != 2) {
printf("usage: %s hostname\n", argv[0]);
printf(" to return the IP addresses for the host\n");
printf(" %s www.contoso.com\n", argv[0]);
printf(" or\n");
printf(" %s IPv4string\n", argv[0]);
printf(" to return an IPv4 binary address for an IPv4string\n");
printf(" %s 127.0.0.1\n", argv[0]);
return 1;
}
// Initialize Winsock
iResult = WSAStartup(MAKEWORD(2, 2), &wsaData);
if (iResult != 0) {
printf("WSAStartup failed: %d\n", iResult);
return 1;
}
host_name = argv[1];
printf("Calling gethostbyname with %s\n", host_name);
remoteHost = gethostbyname(host_name);
if (remoteHost == NULL) {
dwError = WSAGetLastError();
if (dwError != 0) {
if (dwError == WSAHOST_NOT_FOUND) {
printf("Host not found\n");
return 1;
} else if (dwError == WSANO_DATA) {
printf("No data record found\n");
return 1;
} else {
printf("Function failed with error: %ld\n", dwError);
return 1;
}
}
} else {
printf("Function returned:\n");
printf("\tOfficial name: %s\n", remoteHost->h_name);
for (pAlias = remoteHost->h_aliases; *pAlias != 0; pAlias++) {
printf("\tAlternate name #%d: %s\n", ++i, *pAlias);
}
printf("\tAddress type: ");
switch (remoteHost->h_addrtype) {
case AF_INET:
printf("AF_INET\n");
break;
case AF_NETBIOS:
printf("AF_NETBIOS\n");
break;
default:
printf(" %d\n", remoteHost->h_addrtype);
break;
}
printf("\tAddress length: %d\n", remoteHost->h_length);
i = 0;
if (remoteHost->h_addrtype == AF_INET)
{
while (remoteHost->h_addr_list[i] != 0) {
addr.s_addr = *(u_long *) remoteHost->h_addr_list[i++];
printf("\tIP Address #%d: %s\n", i, inet_ntoa(addr));
}
}
else if (remoteHost->h_addrtype == AF_NETBIOS)
{
printf("NETBIOS address was returned\n");
}
}
return 0;
}
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 | wsipv6ok.h (inclua Winsock2.h, Winsock.h) |
| Biblioteca | Ws2_32.lib |
| DLL | Ws2_32.dll |