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

Статья
08/24/2023

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

Синтаксис

NTSYSAPI NTSTATUS RtlIpv6StringToAddressA(
  [in]  PCSTR    S,
  [out] PCSTR    *Terminator,
  [out] in6_addr *Addr
);

Параметры

[in] S

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

[out] Terminator

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

[out] Addr

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

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

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

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

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

Код возврата

Описание

STATUS_INVALID_PARAMETER

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

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

Другое

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

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

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

Строка, на которую указывает параметр S , должна быть представлена в форме для строки адреса IPv6. Базовое строковое представление IPv6-адреса состоит из 8 шестнадцатеричных чисел, разделенных двоеточием. Строка последовательных нулевых чисел может быть заменена двойной двоеточием. В строковом представлении IPv6-адреса может быть только один двойной двоеточие. Последние 32 бита могут быть представлены в нотации IPv4 с точками октета, если адрес является IPv4-совместимым адресом, IPv4-сопоставленным IPv6-адресом или ISATAP-адресом. Дополнительные сведения см. в разделе 5 документа RFC 5942 , опубликованного IETF.

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

Примечание Некоторые неправильно сформированные IPv6-адреса (например::::) начинаются с допустимого IPv6-адреса. Функция RtlIpv6StringToAddress вернет успешное выполнение, проанализировав действительную часть IPv6-адреса в качестве двойного двоеточия (::). Затем признак конца указывает на третий двоеточие. Чтобы убедиться, что вся переданная строка является допустимым IPv6-адресом, необходимо убедиться, что признак конца указывает на правильный символ. Если параметр S содержит только IPv6-адрес, признак конца должен указывать на символ NULL в конце строки.

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

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

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

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

Примечание

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

Требования


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