Функция gethostbyname (winsock2.h)

Статья
08/27/2023

Функция gethostbyname извлекает сведения о узле, соответствующие имени узла, из базы данных узла.

Примечание Функция gethostbyname устарела из-за введения функции getaddrinfo . Разработчикам, создающих приложения Windows Sockets 2, рекомендуется использовать функцию getaddrinfo вместо gethostbyname.

Синтаксис

hostent *WSAAPI gethostbyname(
  const char *name
);

Параметры

name

TBD

Возвращаемое значение

Если ошибки не происходит, gethostbyname возвращает указатель на структуру узла , описанную выше. В противном случае возвращается пустой указатель, и конкретный номер ошибки можно получить, вызвав WSAGetLastError.

Код ошибки	Значение
WSANOTINITIALISED	Перед использованием этой функции должен быть выполнен успешный вызов WSAStartup .
WSAENETDOWN	Произошел сбой сетевой подсистемы.
WSAHOST_NOT_FOUND	Достоверный узел ответа не найден.
WSATRY_AGAIN	Неавторитативный узел не найден или сбой сервера.
WSANO_RECOVERY	Произошла неустранимая ошибка.
WSANO_DATA	Запрошенное имя является допустимым, но данные запрошенного типа не найдены. Эта ошибка также возвращается, если параметр name содержит строковое представление IPv6-адреса или недопустимого IPv4-адреса. Эта ошибка не должна интерпретироваться как означает, что параметр name содержит строку имени, проверенную для определенного протокола (например, имя узла IP- адреса). Так как Winsock поддерживает несколько поставщиков служб имен, имя может быть допустимым для одного поставщика и не приниматься другим поставщиком.
WSAEINPROGRESS	Выполняется блокирующий вызов Windows Sockets 1.1 или поставщик услуг по-прежнему обрабатывает функцию обратного вызова.
WSAEFAULT	Параметр name не является допустимой частью адресного пространства пользователя.
WSAEINTR	Блокирующий вызов сокета Windows 1.1 был отменен через WSACancelBlockingCall.

Функция gethostbyname возвращает указатель на структуру узла — структуру, выделенную сокетами Windows. Структура узла содержит результаты успешного поиска узла, указанного в параметре name .

Если узел, указанный в параметре name , имеет адреса IPv4 и IPv6, будут возвращены только адреса IPv4. Функция gethostbyname может возвращать только IPv4-адреса для параметра name . Функцию getaddrinfo и связанную структуру addrinfo следует использовать, если требуются IPv6-адреса для узла или если требуются адреса IPv4 и IPv6 для узла.

Если параметр name указывает на пустую строку или имеет значениеNULL, возвращаемая строка совпадает со строкой, возвращенной при успешном вызове функции gethostname (стандартное имя узла для локального компьютера).

Если параметр name содержит строковое представление юридического IPv4-адреса, то двоичный IPv4-адрес, представляющий строку, возвращается в структуре узла . Элемент h_name структуры узла содержит строковое представление IPv4-адреса, а h_addr_list — двоичный IPv4-адрес. Если параметр name содержит строковое представление IPv6-адреса или недопустимого IPv4-адреса, функция gethostbyname завершится ошибкой и вернет WSANO_DATA.

Память для структуры узла , возвращаемой функцией gethostbyname , выделяется внутренне библиотекой DLL Winsock из локального хранилища потока. Выделяется и используется только одна структура узла , независимо от того, сколько раз функции gethostbyaddr или gethostbyname вызываются в потоке. Возвращаемая структура узла должна быть скопирована в буфер приложения, если необходимо выполнить дополнительные вызовы функций gethostbyname или gethostbyaddr в том же потоке. В противном случае возвращаемое значение будет перезаписан последующими вызовами gethostbyname или gethostbyaddr в том же потоке. Внутренняя память, выделенная для возвращаемой структуры размещения , освобождается библиотекой DLL Winsock при выходе потока.

Приложение не должно пытаться освободить память, используемую возвращаемой структурой размещения . Приложение никогда не должно пытаться изменить эту структуру или освободить какие-либо из ее компонентов. Кроме того, для каждого потока выделяется только одна копия этой структуры, поэтому приложение должно скопировать все необходимые сведения перед выполнением любых других вызовов функций gethostbyname или gethostbyaddr .

Функция gethostbyname не может принимать строку IP-адреса в качестве параметра, переданного ей в имени , и разрешать ее в имя узла. Такой запрос обрабатывается именно как строковое представление адреса IPv4 или переданного неизвестного имени узла. Приложение может использовать inet_addr для преобразования строки IPv4-адреса в двоичный IPv4-адрес, а затем использовать другую функцию gethostbyaddr для разрешения IPv4-адреса в имя узла.

Примечание Функция gethostbyname не проверка размер параметра name перед передачей буфера. При неправильном размере параметра имени может произойти повреждение кучи.

Пример кода

В следующих примерах показано использование функции 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. Эта функция поддерживается для приложений Магазина Windows Phone Windows Phone 8 и более поздних версий.

Windows 8.1 и Windows Server 2012 R2. Эта функция поддерживается для приложений Магазина Windows в Windows 8.1, Windows Server 2012 R2 и более поздних версий.

Требования

Требование	Значение
Минимальная версия клиента	Windows 8.1, Windows Vista [классические приложения \| Приложения UWP]
Минимальная версия сервера	Windows Server 2003 [классические приложения \| Приложения UWP]
Целевая платформа	Windows
Header	winsock2.h (включая Winsock2.h, Winsock.h)
Библиотека	Ws2_32.lib
DLL	Ws2_32.dll