RtlIpv4StringToAddressA 函数（ip2string.h）

项目
11/20/2024

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

语法

NTSYSAPI NTSTATUS RtlIpv4StringToAddressA(
  [in]  PCSTR   S,
  [in]  BOOLEAN Strict,
  [out] PCSTR   *Terminator,
  [out] in_addr *Addr
);

参数

[in] S

指向包含 IPv4 地址的 NULL终止字符串表示形式的缓冲区的指针。

[in] Strict

一个值，该值指示字符串是否必须是以严格四部分点十进制表示法表示的 IPv4 地址。如果此参数 TRUE，则必须用四个部分对字符串进行点符号十进制。如果此参数 FALSE，则允许使用十进制、八进制或十六进制表示法的四种可能形式中的任何一种。有关详细信息，请参阅“备注”部分。

[out] Terminator

一个参数，该参数接收指向终止转换字符串的字符的指针。调用方可以使用此方法从字符串中提取更多信息。

[out] Addr

一个指针，其中存储 IPv4 地址的二进制表示形式。

返回值

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

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

返回代码	描述
STATUS_INVALID_PARAMETER	将无效参数传递给函数。如果将 Strict 参数设置为 TRUE，则返回此错误，但 S 参数指向的字符串不包含 IPv4 地址的四部分虚点十进制字符串表示形式。如果 S 参数指向的字符串不包含 IPv4 地址的正确字符串表示形式，也会返回此错误。此错误代码在 Ntstatus.h 头文件中定义。
其他	使用 FormatMessage 获取返回错误的消息字符串。

言论

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

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

如果 Strict 参数设置为 TRUE，则由 S 参数指向的字符串必须采用严格的点十进制表示法。此严格格式要求指定四个部分。每个部分被解释为十进制字节的数据，并从左到右分配给 IPv4 地址的四个字节。

当 Strict 参数设置为 FALSE时，S 参数指向的字符串可能采用多种可能的格式之一。当由 S 参数指向的缓冲区包含三部分地址字符串时，最后一部分被解释为 16 位数量，并放置在网络地址最右侧的两个字节中。这使得三部分地址格式便于将类 B 网络地址指定为“128.net.host”。当由 S 参数指向的缓冲区包含两部分地址字符串时，最后一部分被解释为 24 位数量，并放置在网络地址最右侧的三个字节中。这使得两部分地址格式便于将 A 类网络地址指定为“net.host”。当由 S 参数指向的缓冲区仅包含一部分地址字符串时，该值将直接存储在网络地址中，而无需重新排列任何字节。

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

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

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

IN_ADDR 结构在 Inaddr.h 头文件中定义。

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

注意

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

要求

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