RtlIpv6StringToAddressExW 函数 (ip2string.h)

项目
03/13/2024

RtlIpv6StringToAddressEx 函数将 IPv6 地址、范围 ID 和端口号的字符串表示形式转换为二进制 IPv6 地址、范围 ID 和端口。

语法

NTSYSAPI NTSTATUS RtlIpv6StringToAddressExW(
  [in]  PCWSTR   AddressString,
  [out] in6_addr *Address,
  [out] PULONG   ScopeId,
  [out] PUSHORT  Port
);

参数

[in] AddressString

指向缓冲区的指针，该缓冲区包含以 NULL 结尾的 IPv6 地址、范围 ID 和端口号的字符串表示形式。

[out] Address

要存储 IPv6 地址的二进制表示形式的指针。

[out] ScopeId

指向存储 IPv6 地址的范围 ID 的指针。如果 AddressString 参数不包含范围 ID 的字符串表示形式，则此参数中返回零。

[out] Port

存储端口号的指针。端口号采用网络字节顺序格式。如果 AddressString 参数不包含端口号的字符串表示形式，则此参数中返回零。

返回值

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

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

返回代码	说明
STATUS_INVALID_PARAMETER	向该函数传递了无效参数。如果 AddressString 参数指向的字符串不包含 IPv6 地址的正确字符串表示形式，则返回此错误。此错误代码在 Ntstatus.h 头文件中定义。
其他	使用 FormatMessage 获取返回错误的消息字符串。

注解

RtlIpv6StringToAddressEx 函数用于将 IPv6 地址、范围 ID 和端口号的字符串表示形式转换为二进制 IPv6 地址、范围 ID 和端口号。 IPv6 地址按网络顺序返回 (字节从左到右) 。端口号和范围 ID 按网络顺序返回。

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

AddressString 参数指向的字符串必须以 IPv6 地址字符串的形式表示，后跟可选的百分比字符和范围 ID 字符串。 IPv6 地址和范围 ID 字符串必须括在方括号中。 IPv6 地址和范围 ID 字符串后的右方括号后可以跟一个可选的冒号和端口号的字符串表示形式。 IPv6 地址的基本字符串表示形式由 8 个用冒号分隔的十六进制数字组成。连续零数字的字符串可以替换为双冒号。 IPv6 地址的字符串表示形式中只能有一个双冒号。如果地址是 IPv4 兼容地址、IPv4 映射的 IPv6 地址或 ISATAP 地址，则最后 32 位可能以 IPv4 样式的点八进制表示法表示。有关详细信息，请参阅 IETF 发布的 RFC 5942 第 5 部分。

定义 UNICODE 或 _UNICODE 时， RtlIpv6StringToAddressEx 将 定义为 RtlIpv6StringToAddressExW（此函数的 Unicode 版本）。 AddressString 参数定义为 PCWSTR 数据类型。

如果未定义 UNICODE 和 _UNICODE， 则 RtlIpv6StringToAddressEx 将定义为 RtlIpv6StringToAddressExA（此函数的 ANSI 版本）。 AddressString 参数定义为 PCSTR 数据类型。

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

包含 RtlIpv6StringToAddressEx 函数的导入库不包含在针对 Windows Vista 发布的 Microsoft Windows 软件开发工具包 (Windows SDK) (SDK) 中。 RtlIpv6StringToAddressEx 函数包含在 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