Функция 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) по умолчанию. Если параметр pNodeBufferNULL, это означает, что вызывающий объект не хочет получать строку имени узла.
[in] NodeBufferSize
Число символов WCHAR в буфере, на которое указывает параметр pNodeBuffer. Вызывающий объект должен предоставить буфер достаточно большой для хранения имени узла Юникода, в том числе завершающегося символа NULL.
[out] pServiceBuffer
Указатель на строку Юникода для хранения имени службы. При успешном выполнении указатель возвращается в строку Юникода, представляющую имя службы, связанное с номером порта. Если параметр pServiceBufferNULL, это означает, что вызывающий объект не хочет получать строку имени службы.
[in] ServiceBufferSize
Количество символов WCHAR в буфере, на которое указывает параметр pServiceBuffer. Вызывающий объект должен предоставить буфер достаточно большой для хранения имени службы Юникода, включая завершающийся символ NULL.
[in] Flags
Значение, используемое для настройки обработки функции GetNameInfoW. См. раздел "Примечания".
Возвращаемое значение
При успешном выполнении GetNameInfoW возвращает ноль. Любое возвращаемое значение ненулевого значения указывает на сбой, а определенный код ошибки можно получить путем вызова WSAGetLastError.
Коды ошибок, возвращаемых функцией GetNameInfoW
| Значение ошибки | Эквивалент WSA | Описание |
|---|---|---|
| EAI_AGAIN | WSATRY_AGAIN | Произошел временный сбой в разрешении имен. |
| EAI_BADFLAGS | WSAEINVAL | Один или несколько недопустимых параметров переданы функции GetNameInfoW. Эта ошибка возвращается, если запрашивается имя узла, но параметр NodeBufferSize равен нулю или если запрошено имя службы, но параметр ServiceBufferSize был равен нулю. |
| EAI_FAIL | WSANO_RECOVERY | Произошел неустранимый сбой в разрешении имен. |
| EAI_FAMILY | WSAEAFNOSUPPORT | Элемент sa_family структуры адресов сокета, на который указывает параметр pSockaddr, не поддерживается. |
| EAI_MEMORY | WSA_NOT_ENOUGH_MEMORY | Произошел сбой выделения памяти. |
| EAI_NONAME | WSAHOST_NOT_FOUND | Имя службы было запрошено, но номер порта не найден в структуре, на который указывает параметр pSockaddr или имя службы, соответствующее номеру порта, не найдено. NI_NAMEREQD задано, а имя узла не может находиться, или параметры pNodeBuffer и pServiceBuffer были NULL. |
Функцию gai_strerror можно использовать для печати сообщений об ошибках на основе кодов EAI, возвращаемых функцией GetNameInfoW. Функция gai_strerror предоставляется для соответствия рекомендациям IETF, но не является потокобезопасной. Поэтому рекомендуется использовать традиционные функции сокетов Windows, такие как WSAGetLastError.
Кроме того, можно вернуть следующие коды ошибок.
| Код ошибки | Значение |
|---|---|
| Эта ошибка возвращается, если параметр pSockaddrNULL или параметр SockaddrLength меньше длины, необходимой для размера структуры sockaddr_in для IPv4 или структуры sockaddr_in6 для IPv6. |
Замечания
функция 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
Чтобы упростить определение требований к буферу для параметров
#include <windows.h>
#define NI_MAXSERV 32
#define NI_MAXHOST 1025
Параметр Флаги можно использовать для настройки обработки функции GetNameInfoW. Доступны следующие флаги:
- NI_NOFQDN
- NI_NUMERICHOST
- NI_NAMEREQD
- NI_NUMERICSERV
- NI_DGRAM
При установке флага NI_NAMEREQD имя узла, которое не может быть разрешено DNS, приводит к ошибке.
Задание флага
Задание флага NI_NUMERICHOST возвращает числовую форму имени узла вместо его имени. Числовая форма имени узла также возвращается, если имя узла не может быть разрешено DNS.
Задание флага NI_NUMERICSERV возвращает номер порта службы вместо его имени. Кроме того, если имя узла не найдено для IP-адреса (например, 127.0.0.2), имя узла возвращается в качестве IP-адреса.
В Windows Vista и более поздних версиях, если
В Windows Server 2003 и более ранних версий, если
Установка флага 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 и более поздних версий.
пример кода
В следующем примере показано использование функции GetNameInfoW.#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;
}
}
Заметка
Заголовок ws2tcpip.h определяет GetNameInfo как псевдоним, который автоматически выбирает версию этой функции ANSI или Юникод на основе определения константы препроцессора ЮНИКОДа. Сочетание использования псевдонима, нейтрального для кодирования, с кодом, не зависящим от кодирования, может привести к несоответствиям, которые приводят к ошибкам компиляции или среды выполнения. Дополнительные сведения см. в соглашениях о прототипах функций.
Требования
| Требование | Ценность |
|---|---|
| минимальные поддерживаемые клиентские | Windows 8.1, Windows Vista [классические приложения | Приложения UWP] |
| минимальный поддерживаемый сервер | Windows Server 2003 [классические приложения | Приложения UWP] |
| целевая платформа | Виндоус |
| заголовка | ws2tcpip.h |
| библиотеки |
Ws2_32.lib |
| DLL | Ws2_32.dll |
См. также
Справочник