Функция RtlIpv4StringToAddressExW (ip2string.h)

Статья
08/24/2023

Функция RtlIpv4StringToAddressEx преобразует строковое представление IPv4-адреса и номера порта в двоичный IPv4-адрес и порт.

Синтаксис

NTSYSAPI NTSTATUS RtlIpv4StringToAddressExW(
  [in]  PCWSTR  AddressString,
  [in]  BOOLEAN Strict,
  [out] in_addr *Address,
  [out] PUSHORT Port
);

Параметры

[in] AddressString

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

[in] Strict

Значение типа , указывающее, должна ли строка быть адресом IPv4, представленным в строгой четырехкомпонентной десятичной нотации. Если этот параметр имеет значение TRUE, строка должна быть разделена точками с четырьмя частями. Если этот параметр имеет значение FALSE, для строкового представления ipv4-адреса допускается любая из четырех форм с десятичной, восьмеричной или шестнадцатеричной нотацией. Подробные сведения см. в разделе "Заметки".

[out] Address

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

[out] Port

Указатель, в котором должно храниться двоичное представление номера порта. Номер порта возвращается в сетевом порядке байтов. Если в строке, на которую указывает параметр AddressString , не указан ни один порт, то параметру Port присваивается нулевое значение.

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

Если функция выполнена успешно, возвращаемое значение будет STATUS_SUCCESS.

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

Код возврата	Описание
STATUS_INVALID_PARAMETER	В функцию передан недопустимый параметр. Эта ошибка возвращается, если для параметра Strict задано значение TRUE, но строка, на которую указывает параметр AddressString , не содержит четырехкомпонентного десятичного представления IPv4-адреса. Эта ошибка также возвращается, если строка, на которую указывает параметр AddressString , не содержит правильного строкового представления IPv4-адреса. Этот код ошибки определен в файле заголовка Ntstatus.h.
Другое	Используйте FormatMessage , чтобы получить строку сообщения для возвращаемой ошибки.

Код возврата

Описание

STATUS_INVALID_PARAMETER

В функцию передан недопустимый параметр. Эта ошибка возвращается, если для параметра Strict задано значение TRUE, но строка, на которую указывает параметр AddressString , не содержит четырехкомпонентного десятичного представления IPv4-адреса. Эта ошибка также возвращается, если строка, на которую указывает параметр AddressString , не содержит правильного строкового представления IPv4-адреса.

Этот код ошибки определен в файле заголовка Ntstatus.h.

Другое

Используйте FormatMessage , чтобы получить строку сообщения для возвращаемой ошибки.

Функция RtlIpv4StringToAddressEx используется для преобразования строкового представления IPv4-адреса и номера порта в двоичный IPv4-адрес и номер порта. IPv4-адрес возвращается в сетевом порядке (байты, упорядоченные слева направо). Номер порта возвращается в сетевом порядке.

RtlIpv4StringToAddressEx — это удобная функция, которая не требует загрузки библиотеки DLL сокетов Windows для доступа к функции, предоставленной в сокетах Windows, для выполнения преобразования строки в IP-адрес.

Если для параметра Strict задано значение TRUE, строка, на которую указывает параметр AddressString , должна быть строгой десятичной нотацией с точками. Для этого строгого формата необходимо указать четыре части. Каждая часть интерпретируется как десятичный байт данных и назначается слева направо до четырех байтов IPv4-адреса.

Если для параметра Strict задано значение FALSE, строка, на которую указывает параметр AddressString , может иметь любой из нескольких возможных форматов. Если буфер, на который указывает параметр AddressString , содержит строку адреса из трех частей, последняя часть интерпретируется как 16-битное количество и помещается в правые два байта сетевого адреса. Это делает трехкомпонентный формат адресов удобным для указания сетевых адресов класса B как "128.net.host". Если буфер, на который указывает параметр AddressString , содержит строку адреса из двух частей, последняя часть интерпретируется как 24-битное количество и помещается в правые три байта сетевого адреса. Это делает двухкомпонентный формат адресов удобным для указания сетевых адресов класса A в качестве "net.host". Если буфер, на который указывает параметр AddressString , содержит только однокомпонентную строку адреса, значение сохраняется непосредственно в сетевом адресе без переупорядочения байтов.

Буфер, на который указывает параметр AddressString, может содержать строку адреса IPv4, за которой следует необязательный двоеточие и строковое представление номера порта. Если строка номера порта включена в буфер, на который указывает параметр AddressString , двоичное представление номера порта возвращается в параметре Port . Если буфер, на который указывает параметр AddressString , не содержит номера порта, в параметре Port возвращается ноль.

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

Если юникод и _UNICODE не определены, RtlIpv4StringToAddressEx определяется как RtlIpv4StringToAddressExA, версия ANSI этой функции. Параметр AddressString определяется для типа данных PCSTR.

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

Библиотека импорта, содержащая функцию RtlIpv4StringToAddressEx, не включена в microsoft пакет средств разработки программного обеспечения для Windows (SDK), выпущенную для Windows Vista. Функция RtlIpv4StringToAddressEx входит в библиотеку импорта Ntdll.lib , включенную в комплект драйверов Windows (WDK). Приложение также может использовать функции GetModuleHandle и GetProcAddress для получения указателя функции из Ntdll.dll и вызова этой функции.

Требования

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