Função gethostbyname (winsock2.h)

Artigo
03/04/2024

A função gethostbyname recupera informações de host correspondentes a um nome de host de um banco de dados host.

Nota A função gethostbyname foi preterida pela introdução da função getaddrinfo . Os desenvolvedores que criam aplicativos do Windows Sockets 2 são instados a usar a função getaddrinfo em vez de gethostbyname.

Sintaxe

hostent *WSAAPI gethostbyname(
  const char *name
);

Parâmetros

name

TBD

Retornar valor

Se nenhum erro ocorrer, gethostbyname retornará um ponteiro para a estrutura de host descrita acima. Caso contrário, ele retornará um ponteiro nulo e um número de erro específico poderá ser recuperado chamando WSAGetLastError.

Código do erro	Significado
WSANOTINITIALISED	Uma chamada WSAStartup bem-sucedida deve ocorrer antes de usar essa função.
WSAENETDOWN	O subsistema de rede falhou.
WSAHOST_NOT_FOUND	Host de resposta autoritativa não encontrado.
WSATRY_AGAIN	Host nonauthoritative não encontrado ou falha no servidor.
WSANO_RECOVERY	Ocorreu um erro não recuperável.
WSANO_DATA	O nome solicitado é válido, mas nenhum dado do tipo solicitado foi encontrado. Esse erro também será retornado se o parâmetro name contiver uma representação de cadeia de caracteres de um endereço IPv6 ou um endereço IPv4 inválido. Esse erro não deve ser interpretado para significar que o parâmetro name contém uma cadeia de caracteres de nome que foi validada para um protocolo específico (um nome de host IP, por exemplo). Como o Winsock dá suporte a vários provedores de serviços de nome, um nome pode ser potencialmente válido para um provedor e não aceito por outro provedor.
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.
WSAEFAULT	O parâmetro name não é uma parte válida do espaço de endereço do usuário.
WSAEINTR	Uma chamada de bloqueio do Windows Socket 1.1 foi cancelada por meio de WSACancelBlockingCall.

Comentários

A função gethostbyname retorna um ponteiro para uma estrutura de hostent — uma estrutura alocada pelo Windows Sockets. A estrutura do hostent 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 vazia ou o nome 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 do hostent 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 inválido, a função gethostbyname falhará e retornará WSANO_DATA.

A memória da estrutura do hostent retornada pela função gethostbyname é alocada internamente pela DLL do Winsock do armazenamento local do thread. Somente 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 hostent 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 do 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-la a 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 para um nome de host.

Nota A função gethostbyname não marcar o tamanho do parâmetro name antes de passar o buffer. Com um parâmetro de nome de tamanho inadequado, pode ocorrer corrupção de heap.

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	winsock2.h (incluem Winsock2.h, Winsock.h)
Biblioteca	Ws2_32.lib
DLL	Ws2_32.dll