RtlIpv4AddressToStringExW 函数 (ip2string.h)

项目
02/28/2024

RtlIpv4AddressToStringEx 函数将 IPv4 地址和端口号转换为 Internet 标准格式的字符串。

语法

NTSYSAPI NTSTATUS RtlIpv4AddressToStringExW(
  [in]      const in_addr *Address,
  [in]      USHORT        Port,
  [out]     PWSTR         AddressString,
  [in, out] PULONG        AddressStringLength
);

参数

[in] Address

按网络字节顺序排列的 IPv4 地址。

[in] Port

采用网络字节顺序格式的端口号。此参数是可选的。

[out] AddressString

指向缓冲区的指针，用于接收 IPv4 地址和端口的 以 NULL 结尾的字符串表示形式。此缓冲区应足够大，至少可以容纳INET_ADDRSTRLEN个字符。 INET_ADDRSTRLEN值在 Ws2ipdef.h 头文件中定义。

[in, out] AddressStringLength

输入时， AddressString 参数指向的缓冲区中适合的字符数，包括 NULL 终止符。输出时，此参数包含 实际写入 AddressString 参数指向的缓冲区的字符数。

返回值

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

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

返回代码	说明
STATUS_INVALID_PARAMETER	向该函数传递了无效参数。如果在 AddressString 或 AddressStringLength 参数中传递 NULL 指针，则返回此错误。如果 AddressString 参数指向的缓冲区长度不足以接收 IPv4 地址和端口的字符串表示形式，也会返回此错误。
其他	使用 FormatMessage 获取返回错误的消息字符串。

注解

RtlIpv4AddressToStringEx 函数用于将 IPv4 地址和端口号转换为 Internet 虚线十进制格式的 IPv4 地址的字符串表示形式，后跟冒号字符和端口的字符串表示形式。

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

如果 AddressString 参数指向的缓冲区长度不足以接收 IPv4 地址和端口的字符串表示形式， 则 RtlIpv4AddressToStringEx 将返回 ERROR_INVALID_PARAMETER 并将 AddressStringLength 参数设置为所需的缓冲区长度。

定义 UNICODE 或 _UNICODE时， RtlIpv4AddressToStringEx 将定义为 RtlIpv4AddressToStringExW，即此函数的 Unicode 版本。 AddressString 参数定义为 PWSTR 数据类型。

如果未定义 UNICODE 和 _UNICODE， 则 RtlIpv4AddressToStringEx 将定义为 RtlIpv4AddressToStringExA，即此函数的 ANSI 版本。 AddressString 参数定义为 PSTR 数据类型。

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

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