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

Статья
08/28/2023

Функция InetPton преобразует сетевой адрес IPv4 или IPv6 в стандартной форме представления текста в числовую двоичную форму. Версия ANSI этой функции — inet_pton.

Синтаксис

INT WSAAPI InetPtonW(
  [in]  INT    Family,
  [in]  PCWSTR pszAddrString,
  [out] PVOID  pAddrBuf
);

Параметры

[in] Family

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

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

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

Значение	Значение
AF_INET 2	Семейство адресов IPv4. Если указан этот параметр, параметр pszAddrString должен указывать на текстовое представление IPv4-адреса, а параметр pAddrBuf возвращает указатель на структуру IN_ADDR , представляющую IPv4-адрес.
AF_INET6 23	Семейство адресов IPv6. Если указан этот параметр, параметр pszAddrString должен указывать на текстовое представление IPv6-адреса, а параметр pAddrBuf возвращает указатель на структуру IN6_ADDR , представляющую IPv6-адрес.

[in] pszAddrString

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

Если параметр FamilyAF_INET, параметр pszAddrString должен указывать на текстовое представление IPv4-адреса в стандартной десятичной нотации с точками.

Если параметр FamilyAF_INET6, параметр pszAddrString должен указывать на текстовое представление IPv6-адреса в стандартной нотации.

[out] pAddrBuf

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

Если параметр FamilyAF_INET, этот буфер должен быть достаточно большим, чтобы вместить структуру IN_ADDR .

Если параметр FamilyAF_INET6, этот буфер должен быть достаточно большим, чтобы вместить IN6_ADDR структуру.

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

Если ошибка не возникает, функция InetPton возвращает значение 1, а буфер, на который указывает параметр pAddrBuf , содержит двоичный числовой IP-адрес в порядке сетевых байтов.

Функция InetPton возвращает значение 0, если параметр pAddrBuf указывает на строку, которая не является допустимой строкой IPv4-десятичной или допустимой строкой адреса IPv6. В противном случае возвращается значение -1, а определенный код ошибки можно получить, вызвав
WSAGetLastError для расширенных сведений об ошибке.

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

Код ошибки	Значение
WSAEAFNOSUPPORT	Семейство адресов, указанное в параметре Family , не поддерживается. Эта ошибка возвращается, если указанный параметр Family не был AF_INET или AF_INET6.
WSAEFAULT	Параметры pszAddrString или pAddrBuf имеют значение NULL или не являются частью адресного пространства пользователя.

Функция InetPton обеспечивает независимое от протокола преобразование интернет-сетевого адреса в стандартной форме представления текста в числовую двоичную форму. Функция InetPton принимает текстовое представление интернет-адреса, на который указывает параметр pszAddrString , и возвращает указатель на числовой двоичный IP-адрес в параметре pAddrBuf . Хотя функция inet_addr работает только со строками адресов IPv4, функция InetPton работает со строками адресов IPv4 или IPv6.

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

Функция InetPton не требует загрузки библиотеки DLL Windows Sockets для выполнения преобразования текстовой строки, представляющей IP-адрес, в числовой двоичный IP-адрес.

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

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

Если определен ЮНИКОД или _UNICODE, InetPton определяется как InetPtonW, версия юникода этой функции. Параметр pszAddrString определяется для типа данных PCWSTR .

Если юникод или _UNICODE не определены, InetPton определяется как InetPtonA, версия ANSI этой функции. Версия ANSI этой функции всегда определяется как inet_pton. Параметр pszAddrString определяется для типа данных PCSTR .

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

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

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

Windows 8.1 и Windows Server 2012 R2. Функция InetPtonW поддерживается для приложений Магазина 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