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

Статья
08/24/2023

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

Синтаксис

NTSYSAPI NTSTATUS RtlIpv4StringToAddressA(
  [in]  PCSTR   S,
  [in]  BOOLEAN Strict,
  [out] PCSTR   *Terminator,
  [out] in_addr *Addr
);

Параметры

[in] S

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

[in] Strict

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

[out] Terminator

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

[out] Addr

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

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

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

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

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

Код возврата

Описание

STATUS_INVALID_PARAMETER

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

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

Другое

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

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

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

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

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

При успешном выполнении параметр Terminator указывает на символ, завершающий преобразованную строку. Это позволяет приложению передать строку, содержащую IP-адрес и дополнительные сведения, в функцию RtlIpv4StringToAddress , а затем проанализировать оставшиеся сведения.

При определении ЮНИКОДа или _UNICODE RtlIpv4StringToAddress определяется для RtlIpv4StringToAddressW, версии Этой функции в Юникоде. Параметр S определяется для типа данных PCWSTR, а параметр Terminator — для типа данных LPCWSTR.

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

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

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

Примечание

Заголовок ip2string.h определяет RtlIpv4StringToAddress в качестве псевдонима, который автоматически выбирает версию ANSI или Юникод этой функции на основе определения константы препроцессора UNICODE. Сочетание использования псевдонима, не зависящий от кодировки, с кодом, не зависящим от кодировки, может привести к несоответствиям, которые приводят к ошибкам компиляции или среды выполнения. Дополнительные сведения см. в разделе Соглашения для прототипов функций.

Требования


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