Макрос gethostbyname (wsipv6ok.h)

Статья
08/28/2023

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

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

Синтаксис

void gethostbyname(
  [in]  a
);

Параметры

[in] a

Указатель на имя узла, завершаемого null.

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

None

Remarks

Функция gethostbyname возвращает указатель на структуру узла — структуру, выделенную windows Sockets. Структура узла содержит результаты успешного поиска узла, указанного в параметре 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	wsipv6ok.h (включая Winsock2.h, Winsock.h)
Библиотека	Ws2_32.lib
DLL	Ws2_32.dll