RtlIpv4StringToAddressExW 函数 (ip2string.h)

项目
03/05/2024

RtlIpv4StringToAddressEx 函数将 IPv4 地址和端口号的字符串表示形式转换为二进制 IPv4 地址和端口。

语法

NTSYSAPI NTSTATUS RtlIpv4StringToAddressExW(
  [in]  PCWSTR  AddressString,
  [in]  BOOLEAN Strict,
  [out] in_addr *Address,
  [out] PUSHORT Port
);

参数

[in] AddressString

指向缓冲区的指针，该缓冲区包含以 NULL 结尾的 IPv4 地址字符串表示形式，后跟端口号的可选冒号和字符串表示形式。

[in] Strict

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

[out] Address

要存储 IPv4 地址的二进制表示形式的指针。 IPv4 地址按网络字节顺序存储。

[out] Port

要存储端口号的二进制表示形式的指针。端口号按网络字节顺序返回。如果在 AddressString 参数指向的字符串中未指定端口，则 Port 参数设置为零。

返回值

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

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

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

注解

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

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

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

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

AddressString 参数指向的缓冲区可能包含 IPv4 地址字符串，后跟可选的冒号和端口号的字符串表示形式。如果 AddressString 参数指向的缓冲区中包含端口号字符串，则会在 Port 参数中返回端口号的二进制表示形式。如果 AddressString 参数指向的缓冲区不包含端口号，则 Port 参数中返回零。

定义 UNICODE 或 _UNICODE 时， RtlIpv4StringToAddressEx 将定义为 RtlIpv4StringToAddressExW，即此函数的 Unicode 版本。 AddressString 参数定义为 PCWSTR 数据类型。

如果未同时定义 UNICODE 和 _UNICODE， 则 RtlIpv4StringToAddressEx 将定义为 RtlIpv4StringToAddressExA，即此函数的 ANSI 版本。 AddressString 参数定义为 PCSTR 数据类型。

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

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