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

Статья
11/20/2024

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

Синтаксис

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

Параметры

[in] S

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

[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, для выполнения преобразования строк в IP-адрес.

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

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

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

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

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

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

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

Заметка

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

Требования

Требование	Ценность
минимальные поддерживаемые клиентские	Windows Vista [классические приложения \| Приложения UWP]
минимальный поддерживаемый сервер	Windows Server 2008 [классические приложения \| Приложения UWP]
целевая платформа	Виндоус
заголовка	ip2string.h (include Mstcpip.h, Ip2string.h)
библиотеки	ntdll.lib
DLL	ntdll.dll