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

Статья
08/24/2023

Функция RtlIpv6AddressToStringEx преобразует IPv6-адрес, идентификатор область и номер порта в строку.

Синтаксис

NTSYSAPI NTSTATUS RtlIpv6AddressToStringExW(
  [in]      const in6_addr *Address,
  [in]      ULONG          ScopeId,
  [in]      USHORT         Port,
  [out]     PWSTR          AddressString,
  [in, out] PULONG         AddressStringLength
);

Параметры

[in] Address

IPv6-адрес в порядке байтов сети.

[in] ScopeId

Идентификатор область IPv6-адреса в сетевом порядке байтов. Этот параметр является необязательным.

[in] Port

Номер порта в формате сетевого порядка байтов. Этот параметр является необязательным.

[out] AddressString

Указатель на буфер для получения строкового представления IP-адреса, идентификатора область и порта с завершением NULL. Этот буфер должен быть достаточно большим, чтобы вместить не менее INET6_ADDRSTRLEN символов. Значение INET6_ADDRSTRLEN определяется в файле заголовка Ws2ipdef.h .

[in, out] AddressStringLength

Количество символов, помещаемых в буфер, на который указывает параметр AddressString , включая признак конца NULL. В выходных данных этот параметр содержит количество символов, фактически записанных в буфер, на который указывает параметр AddressString .

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

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

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

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

Код возврата

Описание

STATUS_INVALID_PARAMETER

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

Другое

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

Функция RtlIpv6AddressToStringEx используется для преобразования IPv6-адреса, идентификатора область и номера порта в строковое представление IPv6-адреса в формате Интернета, за которым следует строковое представление идентификатора область, за которым следует строковое представление порта. Идентификатор область и номер порта являются необязательными параметрами.

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

Если указан идентификатор область, строковое представление идентификатора область отделяется от строкового представления IPv6-адреса символом процента (%). Если указан номер порта, строковое представление IPv6-адреса и идентификатора область заключаются в квадратные скобки (начальный символ "[", за которым следует адрес IPv6, за которым следует символ "%", за которым следует идентификатор область с символом "]"). Номер порта представлен двоеточием после правой квадратной скобки, за которой следует строковое представление номера порта в десятичном формате.

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

Если длина буфера, на который указывает параметр AddressString, недостаточно велика для получения строкового представления IP-адреса, идентификатора область и порта, RtlIpv6AddressToStringEx возвращает ERROR_INVALID_PARAMETER и задает для параметра AddressStringLength необходимую длину буфера.

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

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

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

Библиотека импорта, содержащая функцию RtlIpv6AddressToStringEx , не входит в пакет средств разработки программного обеспечения Microsoft Windows (SDK), выпущенный для Windows Vista. Функция RtlIpv6AddressToStringEx входит в библиотеку импорта 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