Функция 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.
| Значение ошибки | Эквивалент 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 .
Кроме того, можно вернуть следующие коды ошибок.
| Код ошибки | Значение |
|---|---|
| Эта ошибка возвращается, если параметр pSockaddr имеет значение NULL или параметр 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 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 и более поздних версиях.
Пример кода
В следующем примере показано использование функции 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 или Юникод этой функции на основе определения константы препроцессора UNICODE. Сочетание использования псевдонима, не зависящий от кодировки, с кодом, не зависящим от кодировки, может привести к несоответствиям, которые приводят к ошибкам компиляции или среды выполнения. Дополнительные сведения см. в разделе Соглашения для прототипов функций.
Требования
| Требование | Значение |
|---|---|
| Минимальная версия клиента | Windows 8.1, Windows Vista [классические приложения | Приложения UWP] |
| Минимальная версия сервера | Windows Server 2003 [классические приложения | Приложения UWP] |
| Целевая платформа | Windows |
| Header | ws2tcpip.h |
| Библиотека | Ws2_32.lib |
| DLL | Ws2_32.dll |
См. также раздел
Обратная связь
Ожидается в ближайшее время: в течение 2024 года мы постепенно откажемся от GitHub Issues как механизма обратной связи для контента и заменим его новой системой обратной связи. Дополнительные сведения см. в разделе https://aka.ms/ContentUserFeedback.
Отправить и просмотреть отзыв по