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

Статья
03/13/2024

Функция InetNtop преобразует интернет-адрес IPv4 или IPv6 в строку в стандартном формате Интернета. Версия ANSI этой функции inet_ntop.

Синтаксис

PCWSTR WSAAPI InetNtopW(
  [in]  INT        Family,
  [in]  const VOID *pAddr,
  [out] PWSTR      pStringBuf,
  [in]  size_t     StringBufSize
);

Параметры

[in] Family

Семейство адресов.

Возможные значения для семейства адресов определяются в файле заголовка Ws2def.h . Обратите внимание, что файл заголовка Ws2def.h автоматически включается в Winsock2.h и никогда не должен использоваться напрямую. Обратите внимание, что значения для семейства адресов AF_ и констант семейства протоколов PF_ идентичны (например, AF_INET и PF_INET), поэтому можно использовать любой из констант.

В настоящее время поддерживаются значения AF_INET и AF_INET6.

Значение	Значение
AF_INET 2	Семейство адресов IPv4. Если указан этот параметр, эта функция возвращает строку адреса IPv4.
AF_INET6 23	Семейство адресов IPv6. Если указан этот параметр, эта функция возвращает строку адреса IPv6.

[in] pAddr

Указатель на IP-адрес в сетевом байте для преобразования в строку.

Если параметр FamilyAF_INET, то параметр pAddr должен указывать на структуру IN_ADDR с IPv4-адресом для преобразования.

Если параметр FamilyAF_INET6, параметр pAddr должен указывать на структуру IN6_ADDR с IPv6-адресом для преобразования.

[out] pStringBuf

Указатель на буфер, в котором будет храниться строковое представление IP-адреса, завершающееся значением NULL.

Для IPv4-адреса этот буфер должен быть достаточно большим и содержать не менее 16 символов.

Для IPv6-адреса этот буфер должен быть достаточно большим и содержать не менее 46 символов.

[in] StringBufSize

Во входных данных длина буфера в символах, на которую указывает параметр pStringBuf .

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

Если ошибка не возникает, функция InetNtop возвращает указатель на буфер, содержащий строковое представление IP-адреса в стандартном формате.

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

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

Код ошибки	Значение
WSAEAFNOSUPPORT	Семейство адресов, указанное в параметре Family , не поддерживается. Эта ошибка возвращается, если указанный параметр Family не был AF_INET или AF_INET6.
ERROR_INVALID_PARAMETER	В функцию передан недопустимый параметр. Эта ошибка возвращается, если указатель NULL передается в pStringBuf или параметр StringBufSize равен нулю. Эта ошибка также возвращается, если длина буфера, на который указывает параметр pStringBuf , недостаточно велика для получения строкового представления IP-адреса.

Код ошибки

Значение

WSAEAFNOSUPPORT

Семейство адресов, указанное в параметре Family , не поддерживается. Эта ошибка возвращается, если указанный параметр Family не был AF_INET или AF_INET6.

ERROR_INVALID_PARAMETER

В функцию передан недопустимый параметр. Эта ошибка возвращается, если указатель NULL передается в pStringBuf или параметр StringBufSize равен нулю. Эта ошибка также возвращается, если длина буфера, на который указывает параметр pStringBuf , недостаточно велика для получения строкового представления IP-адреса.

Функция InetNtop обеспечивает независимое от протокола преобразование адреса в строку. Функция InetNtop принимает структуру интернет-адресов, заданную параметром pAddr , и возвращает строку с завершением NULL, представляющую IP-адрес. Хотя функция inet_ntoa работает только с IPv4-адресами, функция InetNtop работает с адресами IPv4 или IPv6.

Версия ANSI этой функции inet_ntop , как определено в RFC 2553. Дополнительные сведения см. в статье RFC 2553, доступной на веб-сайте IETF.

Функция InetNtop не требует загрузки библиотеки DLL сокетов Windows для преобразования IP-адреса в строку.

Если параметр Family указан AF_INET, то параметр pAddr должен указывать на структуру IN_ADDR с IPv4-адресом для преобразования. Строка адреса, возвращаемая в буфере, на который указывает параметр pStringBuf , имеет пунктирную десятичную нотацию, как в "192.168.16.0", пример IPv4-адреса в точечной десятичной нотации.

Если параметр Family указан AF_INET6, то параметр pAddr должен указывать на структуру IN6_ADDR с IPv6-адресом для преобразования. Строка адреса, возвращаемая в буфере, на который указывает параметр pStringBuf , имеет стандартный для Интернета формат. Базовое строковое представление состоит из 8 шестнадцатеричных чисел, разделенных двоеточиями. Строка последовательных нулевых чисел заменяется двойной двоеточием. В строковом представлении IPv6-адреса может быть только один двойной двоеточие. Последние 32 бита представлены в нотации iPv4-точечных октетов, если адрес является адресом, совместимым с IPv4.

Если длина буфера, на который указывает параметр pStringBuf , недостаточно велика для получения строкового представления IP-адреса, InetNtop возвращает ERROR_INVALID_PARAMETER.

При определении ЮНИКОДа или _UNICODE inetNtop определяется как InetNtopW, версия юникода этой функции. Параметр pStringBuf определяется для типа данных PSTR .

Если юникод или _UNICODE не определены, InetNtop определяется как InetNtopA, версия ANSI этой функции. Версия ANSI этой функции всегда определяется как inet_ntop. Параметр pStringBuf определяется для типа данных PWSTR .

Структура IN_ADDR определяется в файле заголовка Inaddr.h .

Структура IN6_ADDR определена в файле заголовка In6addr.h .

В Windows Vista и более поздних версиях функции RtlIpv4AddressToString и RtlIpv4AddressToStringEx можно использовать для преобразования IPv4-адреса, представленного в виде структуры IN_ADDR , в строковое представление IPv4-адреса в стандартной десятичной нотации Интернета. В Windows Vista и более поздних версиях функции RtlIpv6AddressToString и RtlIpv6AddressToStringEx можно использовать для преобразования IPv6-адреса, представленного в виде структуры IN6_ADDR , в строковое представление IPv6-адреса. Функция RtlIpv6AddressToStringEx более гибкая, так как она также преобразует IPv6-адрес, идентификатор область и порт в строку IPv6 в стандартном формате.

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

Требования

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