inetNtopW 函数 (ws2tcpip.h)

项目
03/13/2024

InetNtop 函数将 IPv4 或 IPv6 Internet 网络地址转换为 Internet 标准格式的字符串。此函数的 ANSI 版本 inet_ntop。

语法

PCWSTR WSAAPI InetNtopW(
  [in]  INT        Family,
  [in]  const VOID *pAddr,
  [out] PWSTR      pStringBuf,
  [in]  size_t     StringBufSize
);

参数

[in] Family

地址系列。

地址系列的可能值在 Ws2def.h 头文件中定义。请注意， Ws2def.h 头文件自动包含在 Winsock2.h 中，不应直接使用。请注意，AF_地址系列和PF_协议系列常量的值 (相同，例如 ，AF_INET 和 PF_INET) ，因此可以使用任一常量。

当前支持的值AF_INET和AF_INET6。

值	含义
AF_INET 2	Internet 协议版本 4 (IPv4) 地址系列。指定此参数时，此函数将返回 IPv4 地址字符串。
AF_INET6 23	Internet 协议版本 6 (IPv6) 地址系列。指定此参数后，此函数将返回 IPv6 地址字符串。

[in] pAddr

指向网络字节中要转换为字符串的 IP 地址的指针。

AF_INETFamily 参数时，pAddr 参数必须指向具有要转换的 IPv4 地址的IN_ADDR结构。

AF_INET6Family 参数时，pAddr 参数必须指向具有要转换的 IPv6 地址的IN6_ADDR结构。

[out] pStringBuf

指向存储 IP 地址的 以 NULL 结尾的字符串表示形式的缓冲区的指针。

对于 IPv4 地址，此缓冲区的大小应足以容纳至少 16 个字符。

对于 IPv6 地址，此缓冲区的大小应足以容纳至少 46 个字符。

[in] StringBufSize

输入时， pStringBuf 参数指向的缓冲区的长度（以字符为单位）。

返回值

如果未发生错误， InetNtop 函数将返回指向缓冲区的指针，该缓冲区包含标准格式 IP 地址的字符串表示形式。

否则，返回 NULL 值，并且可以通过调用来检索特定的错误代码
WSAGetLastError ，用于扩展错误信息。

如果函数失败， WSAGetLastError 返回的扩展错误代码可以是以下值之一。

错误代码	含义
WSAEAFNOSUPPORT	不支持 Family 参数中指定的地址系列。如果指定的 Family 参数未 AF_INET 或 AF_INET6，则返回此错误。
ERROR_INVALID_PARAMETER	向该函数传递了无效参数。如果在 pStringBuf 中传递 NULL 指针或 StringBufSize 参数为零，则返回此错误。如果 pStringBuf 参数指向的缓冲区长度不足以接收 IP 地址的字符串表示形式，也会返回此错误。

注解

Windows Vista 及更高版本支持 InetNtop 函数。

InetNtop 函数提供与协议无关的地址到字符串转换。 InetNtop 函数采用 pAddr 参数指定的 Internet 地址结构，并返回一个以 NULL 结尾的字符串，该字符串表示 IP 地址。虽然 inet_ntoa 函数仅适用于 IPv4 地址，但 InetNtop 函数适用于 IPv4 或 IPv6 地址。

此函数的 ANSI 版本 inet_ntop RFC 2553 中的定义。有关详细信息，请参阅 IETF 网站上提供的 RFC 2553。

InetNtop 函数不要求加载 Windows 套接字 DLL 来执行 IP 地址到字符串的转换。

如果指定的 Family 参数 AF_INET，则 pAddr 参数必须指向具有要转换的 IPv4 地址的IN_ADDR 结构。 pStringBuf 参数指向的缓冲区中返回的地址字符串采用点十进制表示法，如“192.168.16.0”一样，这是采用点数十进制表示法的 IPv4 地址的示例。

如果指定的 Family 参数 AF_INET6，则 pAddr 参数必须指向具有要转换的 IPv6 地址的 IN6_ADDR 结构。 pStringBuf 参数指向的缓冲区中返回的地址字符串采用 Internet 标准格式。基本字符串表示形式由 8 个用冒号分隔的十六进制数字组成。由连续零数字的字符串替换为双冒号。 IPv6 地址的字符串表示形式中只能有一个双冒号。如果地址是 IPv4 兼容地址，则最后 32 位以 IPv4 样式的点位八进制表示法表示。

如果 pStringBuf 参数指向的缓冲区长度不足以接收 IP 地址的字符串表示形式， 则 InetNtop 将返回ERROR_INVALID_PARAMETER。

定义 UNICODE 或 _UNICODE 时， 将 InetNtop 定义为 InetNtopW，即此函数的 Unicode 版本。 pStringBuf 参数定义为 PSTR 数据类型。

如果未定义 UNICODE 或 _UNICODE， 则 InetNtop 将定义为此函数的 ANSI 版本 InetNtopA。此函数的 ANSI 版本始终定义为 inet_ntop。 pStringBuf 参数定义为 PWSTR 数据类型。

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

IN6_ADDR 结构在 In6addr.h 头文件中定义。

在 Windows Vista 及更高版本中， RtlIpv4AddressToString 和 RtlIpv4AddressToStringEx 函数可用于将表示为 IN_ADDR 结构的 IPv4 地址转换为 Internet 标准点十进制表示法中的 IPv4 地址的字符串表示形式。在 Windows Vista 及更高版本上， RtlIpv6AddressToString 和 RtlIpv6AddressToStringEx 函数可用于将表示为 IN6_ADDR 结构的 IPv6 地址转换为 IPv6 地址的字符串表示形式。 RtlIpv6AddressToStringEx 函数更加灵活，因为它还可以将 IPv6 地址、范围 ID 和端口转换为标准格式的 IPv6 字符串。

Windows 8.1和Windows Server 2012 R2：Windows 8.1、Windows Server 2012 R2 及更高版本的 Windows 应用商店应用支持 InetNtopW 函数。

要求

要求	值
最低受支持的客户端	Windows 8.1、Windows Vista [桌面应用 \|UWP 应用]
最低受支持的服务器	Windows Server 2008 [桌面应用 \| UWP 应用]
目标平台	Windows
标头	ws2tcpip.h
Library	Ws2_32.lib
DLL	Ws2_32.dll