RtlIpv6StringToAddressW 函数 (ip2string.h)

项目
08/24/2023

RtlIpv6StringToAddress 函数将 IPv6 地址的字符串表示形式转换为二进制 IPv6 地址。

语法

NTSYSAPI NTSTATUS RtlIpv6StringToAddressW(
  [in]  PCWSTR   S,
  [out] PCWSTR   *Terminator,
  [out] in6_addr *Addr
);

参数

[in] S

指向缓冲区的指针，该缓冲区包含以 NULL 结尾的 IPv6 地址的字符串表示形式。

[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 样式的点位八位表示法表示。有关详细信息，请参阅 IETF 发布的 RFC 5942 的第 5 部分。

成功后， Terminator 参数指向终止已转换的字符串的字符。这允许应用程序将包含和 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 头文件中定义。

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

注意

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

要求

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