RtlIpv6StringToAddressA 函数（ip2string.h）

项目
11/20/2024

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 获取返回错误的消息字符串。

言论

RtlIpv6StringToAddress 函数用于将 IPv6 地址的字符串表示形式转换为按网络顺序返回的 IPv6 地址（从左到右排序的字节）。

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

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

成功后，终止符 参数指向终止已转换字符串的字符。这允许应用程序将包含和 IP 地址的字符串以及附加信息传递给 RtlIpv6StringToAddress 函数，然后分析其余信息。

注意一些格式不正确的 IPv6 地址（：：：例如）以有效的 IPv6 地址开头。 RtlIpv6StringToAddress 函数将返回成功，将 IPv6 地址的有效部分分析为双冒号（：:)）。然后，终止符指向第三个冒号。若要验证整个传入字符串是否为有效的 IPv6 地址，需要确保终止符指向正确的字符。如果 S 参数仅包含 IPv6 地址，则终止符应指向字符串末尾的 NULL 字符。

定义 UNICODE 或_UNICODE时，RtlIpv6StringToAddress 定义为 RtlIpv6StringToAddressW（此函数的 Unicode 版本）。 S 和 终止符 参数定义为 PCWSTR 数据类型。

如果未定义 UNICODE 和_UNICODE，则 RtlIpv6StringToAddress 定义为 RtlIpv6StringToAddressA（此函数的 ANSI 版本）。 S 和 终止符 参数定义为 PCSTR 数据类型。

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

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

注意

ip2string.h 标头将 RtlIpv6StringToAddress 定义为一个别名，该别名根据 UNICODE 预处理器常量的定义自动选择此函数的 ANSI 或 Unicode 版本。将中性编码别名与不中性编码的代码混合使用可能会导致编译或运行时错误不匹配。有关详细信息，请参阅函数原型的约定。

要求

要求	价值
最低支持的客户端	Windows Vista [桌面应用 \|UWP 应用]
支持的最低服务器	Windows Server 2008 [桌面应用 \|UWP 应用]
目标平台	窗户
标头	ip2string.h（包括 Mstcpip.h、Ip2string.h）
库	ntdll.lib
DLL	ntdll.dll