RtlIpv6AddressToStringExW 函数 (ip2string.h)

项目
01/27/2024

RtlIpv6AddressToStringEx 函数将 IPv6 地址、范围 ID 和端口号转换为字符串。

语法

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 地址的范围 ID。此参数是可选的。

[in] Port

网络字节顺序格式的端口号。此参数是可选的。

[out] AddressString

指向缓冲区的指针，用于接收 IP 地址、范围 ID 和端口的 以 NULL 结尾的字符串表示形式。此缓冲区应足够大，以容纳至少INET6_ADDRSTRLEN个字符。 INET6_ADDRSTRLEN值在 Ws2ipdef.h 头文件中定义。

[in, out] AddressStringLength

输入时， AddressString 参数指向的缓冲区中适合的字符数，包括 NULL 终止符。在输出时，此参数包含实际写入 到 AddressString 参数指向的缓冲区的字符数。

返回值

如果函数成功，则返回值 STATUS_SUCCESS。

如果函数失败，则返回值为以下错误代码之一。

返回代码	说明
STATUS_INVALID_PARAMETER	向该函数传递了无效参数。如果在 AddressString 或 AddressStringLength 参数中传递 NULL 指针，则返回此错误。如果 AddressString 参数指向的缓冲区长度不足以接收 IPv6 地址、范围 ID 和端口的字符串表示形式，则也会返回此错误。
其他	使用 FormatMessage 获取返回错误的消息字符串。

注解

RtlIpv6AddressToStringEx 函数用于将 IPv6 地址、范围 ID 和端口号转换为 Internet 格式的 IPv6 地址的字符串表示形式，后跟范围 ID 的字符串表示形式，后跟端口的字符串表示形式。范围 ID 和端口号是可选参数。

返回的 IPv6 地址的基本字符串表示形式由 8 个用冒号分隔的十六进制数组成。连续零个十六进制数字的字符串将替换为双冒号。 IPv6 地址的字符串表示形式中只能有一个双冒号。如果地址是 IPv4 兼容地址、IPv4 映射的 IPv6 地址或 ISATAP 地址，则最后 32 位以 IPv4 样式的点八进制表示法表示。有关详细信息，请参阅 IETF 发布的 RFC 5942 第 5 部分。

如果提供了范围 ID，则范围 ID 的字符串表示形式与 IPv6 地址的字符串表示形式 ('%') 分隔。如果提供了端口号，则 IPv6 地址和范围 ID 的字符串表示形式用方括号括起来， (前导的“[”字符，后跟 IPv6 地址，后跟一个“% 字符，后跟一个带有尾随”]“字符的范围 ID) 。端口号表示为一个冒号，后跟右方括号字符，后跟端口号的字符串表示形式（以十进制为单位）。

RtlIpv6AddressToStringEx 是一个方便函数，它不需要加载 Windows 套接字 DLL 即可访问 Windows 套接字中提供的函数，以执行 IP 地址到字符串的转换。

如果 AddressString 参数指向的缓冲区长度不足以接收 IP 地址、范围 ID 和端口的字符串表示形式， 则 RtlIpv6AddressToStringEx 将返回 ERROR_INVALID_PARAMETER 并将 AddressStringLength 参数设置为所需的缓冲区长度。

定义 UNICODE 或 _UNICODE 时， RtlIpv6AddressToStringEx 将定义为 RtlIpv6AddressToStringExW，即此函数的 Unicode 版本。 AddressString 参数定义为 PWSTR 数据类型。

如果未定义 UNICODE 和 _UNICODE， 则 RtlIpv6AddressToStringEx 定义为 RtlIpv6AddressToStringExA（此函数的 ANSI 版本）。 AddressString 参数定义为 PSTR 数据类型。

IN6_ADDR 结构在 In6addr.h 头文件中定义。

包含 RtlIpv6AddressToStringEx 函数的导入库不包含在针对 Windows Vista 发布的 Microsoft Windows 软件开发工具包 (SDK) 中。 RtlIpv6AddressToStringEx 函数包含在 Windows 驱动程序工具包 (WDK) 中包含的 Ntdll.lib 导入库中。应用程序还可以使用 GetModuleHandle 和 GetProcAddress 函数从 Ntdll.dll 检索函数指针并调用此函数。

要求


最低受支持的客户端	Windows Vista [桌面应用 \| UWP 应用]
最低受支持的服务器	Windows Server 2008 [桌面应用 \| UWP 应用]
目标平台	Windows
标头	ip2string.h (包括 Mstcpip.h)
Library	ntdll.lib
DLL	ntdll.dll