Функция GetNameInfoW (ws2tcpip.h)

Функция GetNameInfoW обеспечивает независимое от протокола разрешение имен от адреса до имени узла Юникода и от номера порта до имени службы Юникода.

Синтаксис

INT WSAAPI GetNameInfoW(
  [in]  const SOCKADDR *pSockaddr,
  [in]  socklen_t      SockaddrLength,
  [out] PWCHAR         pNodeBuffer,
  [in]  DWORD          NodeBufferSize,
  [out] PWCHAR         pServiceBuffer,
  [in]  DWORD          ServiceBufferSize,
  [in]  INT            Flags
);

Параметры

[in] pSockaddr

Указатель на структуру адресов сокета, содержащую IP-адрес и номер порта сокета. Для IPv4 параметр pSockaddr указывает на структуру sockaddr_in . Для IPv6 параметр pSockaddr указывает на структуру sockaddr_in6 .

[in] SockaddrLength

Длина структуры в байтах, на которую указывает параметр pSockaddr .

[out] pNodeBuffer

Указатель на строку Юникода для хранения имени узла. При успешном выполнении указатель на имя узла Юникода по умолчанию возвращается в виде полного доменного имени (FQDN). Если параметр pNodeBuffer имеет значение NULL, это означает, что вызывающий объект не хочет получать строку имени узла.

[in] NodeBufferSize

Количество символов WCHAR в буфере, на который указывает параметр pNodeBuffer . Вызывающий объект должен предоставить буфер, достаточный для хранения имени узла Юникода, включая завершающий символ NULL .

[out] pServiceBuffer

Указатель на строку Юникода для хранения имени службы. При успешном выполнении указатель возвращается в строку Юникода, представляющую имя службы, связанное с номером порта. Если параметр pServiceBuffer имеет значение NULL, это означает, что вызывающий объект не хочет получать строку имени службы.

[in] ServiceBufferSize

Количество символов WCHAR в буфере, на которое указывает параметр pServiceBuffer . Вызывающий объект должен предоставить буфер, достаточно большой для хранения имени службы Юникода, включая завершающий символ NULL .

[in] Flags

Значение, используемое для настройки обработки функции GetNameInfoW . См. раздел «Примечания».

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

При успешном выполнении GetNameInfoW возвращает ноль. Любое ненулевое возвращаемое значение указывает на сбой, и конкретный код ошибки можно получить, вызвав WSAGetLastError.

Ненулевые коды ошибок, возвращаемые функцией GetNameInfoW , также сопоставляются с набором ошибок, описанным в рекомендациях Internet Engineering Task Force (IETF). В следующей таблице показаны эти коды ошибок и их эквиваленты WSA. Рекомендуется использовать коды ошибок WSA, так как они предоставляют знакомые и исчерпывающие сведения об ошибках для программистов Winsock.

Функцию gai_strerror можно использовать для печати сообщений об ошибках на основе кодов EAI, возвращаемых функцией GetNameInfoW . Функция gai_strerror предоставляется для соответствия рекомендациям IETF, но не является потокобезопасной. Поэтому рекомендуется использовать традиционные функции сокетов Windows, такие как WSAGetLastError .

Кроме того, можно вернуть следующие коды ошибок.

Комментарии

Функция GetNameInfoW — это версия функции в Юникоде, которая обеспечивает независимое от протокола разрешение имен. Функция GetNameInfoW используется для преобразования содержимого структуры адресов сокета в имя узла и (или) имя службы.

Для протоколов IPv6 и IPv4 разрешение имен может осуществляться системой доменных имен (DNS), локальным файлом узлов или другими механизмами именования. Эта функция может использоваться для определения имени узла для адреса IPv4 или IPv6, обратного поиска DNS или определения имени службы для номера порта. Функцию GetNameInfoW также можно использовать для преобразования IP-адреса или номера порта в структуре SOCKADDR в строку Юникода. Эту функцию также можно использовать для определения IP-адреса для имени узла.

Версия ANSI этой функции — getnameinfo.

Макросы в файле заголовка Winsock определяют имя функции GetNameInfo в смешанном регистре, которое можно использовать, если приложение предназначено для Windows XP с пакетом обновления 2 (SP2) и более поздних версий (_WIN32_WINNT >= 0x0502). Эта функция GetNameInfo должна вызываться с параметрами pNodeBuffer и pServiceBuffer указателя типа TCHAR. При определении ЮНИКОДа или _UNICODE getNameInfo определяется для версии Юникода, а Метод GetNameInfoW вызывается с параметрами host и serv указателя типа char. Если юникод или _UNICODE не определены, getNameInfo определяется для версии ANSI и getnameinfo вызывается с параметрами pNodeBuffer и pServiceBuffer указателя типа PWCHAR.

Чтобы упростить определение требований к буферу для параметров pNodeBuffer и pServiceBuffer , в файле заголовка Ws2tcpip.h определяются следующие значения максимальной длины имени узла и максимального имени службы:

#include <windows.h>

#define NI_MAXSERV    32
#define NI_MAXHOST  1025

Параметр Flags можно использовать для настройки обработки функции GetNameInfoW . Доступны следующие флаги:

• NI_NOFQDN
• NI_NUMERICHOST
• NI_NAMEREQD
• NI_NUMERICSERV
• NI_DGRAM

Если установлен флаг NI_NAMEREQD , имя узла, которое не может быть разрешено DNS, приводит к ошибке.

Установка флага NI_NOFQDN приводит к тому, что в параметре pNodeBuffer локальные узлы возвращаются только относительное различающееся имя (RDN).

Установка флага NI_NUMERICHOST возвращает числовую форму имени узла вместо его имени. Числовая форма имени узла также возвращается, если имя узла не может быть разрешено DNS.

Установка флага NI_NUMERICSERV возвращает номер порта службы вместо ее имени. Кроме того, если имя узла не найдено для IP-адреса (например, 127.0.0.2), имя узла возвращается в качестве IP-адреса.

В Windows Vista и более поздних версиях, если NI_NUMERICSERV не указан в параметре flags , а номер порта, содержащийся в структуре sockaddr , на который указывает параметр sa , не разрешается в хорошо известную службу, функция GetNameInfoW возвращает числовую форму адреса службы (номер порта) в виде числовой строки. При указании NI_NUMERICSERV номер порта возвращается в виде числовой строки. Это поведение указано в разделе 6.2 документа RFC 3493. Дополнительные сведения см. в разделе www.ietf.org/rfc/rfc3493.txt

В Windows Server 2003 и более ранних версиях, если NI_NUMERICSERV не указан в параметре flags , а номер порта, содержащийся в структуре sockaddr, на который указывает параметр sa , не разрешается в хорошо известную службу, функция GetNameInfoW завершается ошибкой. При указании NI_NUMERICSERV номер порта возвращается в виде числовой строки.

Установка флага NI_DGRAM означает, что служба является службой датаграмм. Этот флаг необходим для нескольких служб, которые предоставляют разные номера портов для службы UDP и TCP.

Windows Phone 8. Эта функция поддерживается для приложений Магазина Windows Phone на Windows Phone 8 и более поздних версиях.

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

Пример кода

#ifndef UNICODE
#define UNICODE
#endif

#define WIN32_LEAN_AND_MEAN

#include <winsock2.h>
#include <Ws2tcpip.h>
#include <stdio.h>

// Link with ws2_32.lib
#pragma comment(lib, "Ws2_32.lib")

int __cdecl main(int argc, char **argv)
{

    //-----------------------------------------
    // Declare and initialize variables
    WSADATA wsaData;
    int iResult;

    DWORD dwRetval;

    struct sockaddr_in saGNI;
    WCHAR hostname[NI_MAXHOST];
    WCHAR servInfo[NI_MAXSERV];
    u_short port = 27015;

    // Validate the parameters
    if (argc != 2) {
        wprintf(L"usage: %s IPv4 address\n", argv[0]);
        wprintf(L"  to return hostname\n");
        wprintf(L"       %s 127.0.0.1\n", argv[0]);
        return 1;
    }
    // Initialize Winsock
    iResult = WSAStartup(MAKEWORD(2, 2), &wsaData);
    if (iResult != 0) {
        wprintf(L"WSAStartup failed: %d\n", iResult);
        return 1;
    }
    //-----------------------------------------
    // Set up sockaddr_in structure which is passed
    // to the getnameinfo function
    saGNI.sin_family = AF_INET;
    saGNI.sin_addr.s_addr = inet_addr(argv[1]);
    saGNI.sin_port = htons(port);

    //-----------------------------------------
    // Call GetNameInfoW
    dwRetval = GetNameInfoW((struct sockaddr *) &saGNI,
                           sizeof (struct sockaddr),
                           hostname,
                           NI_MAXHOST, servInfo, NI_MAXSERV, NI_NUMERICSERV);

    if (dwRetval != 0) {
        wprintf(L"GetNameInfoW failed with error # %ld\n", WSAGetLastError());
        return 1;
    } else {
        wprintf(L"GetNameInfoW returned hostname = %ws\n", hostname);
        return 0;
    }
}

Требования

См. также раздел

GetAddrInfoW

WSAGetLastError

Функции Winsock

Справочник по Winsock

gai_strerror

getaddrinfo

getnameinfo

sockaddr