RtlIpv4StringToAddressA 函数 (ip2string.h)

项目
02/01/2024

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

语法

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

参数

[in] S

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

[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 参数指向的缓冲区仅包含一部分地址字符串时，该值将直接存储在网络地址中，而无需进行任何字节重新排列。

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

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

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

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

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

注意

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

要求


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