inetPtonW 函数 (ws2tcpip.h)

项目
08/28/2023

InetPton 函数将标准文本表示形式的 IPv4 或 IPv6 Internet 网络地址转换为数字二进制形式。此函数的 ANSI 版本 inet_pton。

语法

INT WSAAPI InetPtonW(
  [in]  INT    Family,
  [in]  PCWSTR pszAddrString,
  [out] PVOID  pAddrBuf
);

参数

[in] Family

地址系列。

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

当前支持的值AF_INET和AF_INET6。

值	含义
AF_INET 2	Internet 协议版本 4 (IPv4) 地址系列。指定此参数时， pszAddrString 参数必须指向 IPv4 地址的文本表示形式， pAddrBuf 参数返回指向表示 IPv4 地址的IN_ADDR 结构的指针。
AF_INET6 23	Internet 协议版本 6 (IPv6) 地址系列。指定此参数时， pszAddrString 参数必须指向 IPv6 地址的文本表示形式， pAddrBuf 参数返回指向表示 IPv6 地址的IN6_ADDR 结构的指针。

[in] pszAddrString

指向以 NULL 结尾的字符串的指针，该字符串包含要转换为数字二进制形式的 IP 地址的文本表示形式。

当 Family 参数 AF_INET时， pszAddrString 参数必须以标准点十进制表示法指向 IPv4 地址的文本表示形式。

当 Family 参数 AF_INET6时， pszAddrString 参数必须以标准表示法指向 IPv6 地址的文本表示形式。

[out] pAddrBuf

指向存储 IP 地址的数字二进制表示形式的缓冲区的指针。 IP 地址按网络字节顺序返回。

AF_INETFamily 参数时，此缓冲区应足够大，可以容纳IN_ADDR结构。

AF_INET6Family 参数时，此缓冲区应足够大，可以容纳IN6_ADDR结构。

返回值

如果未发生错误， InetPton 函数将返回值 1，pAddrBuf 参数指向的缓冲区包含网络字节顺序中的二进制数字 IP 地址。

如果 pAddrBuf 参数指向的字符串不是有效的 IPv4 点十进制字符串或有效的 IPv6 地址字符串，则 InetPton 函数将返回值 0。否则，将返回值 -1，并且可以通过调用来检索特定的错误代码
WSAGetLastError ，用于扩展错误信息。

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

错误代码	含义
WSAEAFNOSUPPORT	不支持 Family 参数中指定的地址系列。如果指定的 Family 参数未 AF_INET 或 AF_INET6，则返回此错误。
WSAEFAULT	pszAddrString 或 pAddrBuf 参数为 NULL 或不属于用户地址空间。

注解

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

InetPton 函数在其标准文本表示形式中提供 Internet 网络地址到数字二进制形式的独立于协议的转换。 InetPton 函数采用 pszAddrString 参数指向的 Internet 地址的文本表示形式，并返回指向 pAddrBuf 参数中数字二进制 IP 地址的指针。虽然 inet_addr 函数仅适用于 IPv4 地址字符串，但 InetPton 函数适用于 IPv4 或 IPv6 地址字符串。

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

InetPton 函数不要求加载 Windows 套接字 DLL 来执行将表示 IP 地址的文本字符串转换为数字二进制 IP 地址。

如果指定的 Family 参数 为 AF_INET，则 pszAddrString 参数必须以点十进制表示法指向 IPv4 地址的文本字符串，如“192.168.16.0”中所示，这是以点十进制表示法表示的 IPv4 地址的示例。

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

定义 UNICODE 或 _UNICODE 时， 将 InetPton 定义为此函数的 Unicode 版本 InetPtonW。 pszAddrString 参数定义为 PCWSTR 数据类型。

如果未定义 UNICODE 或 _UNICODE， 则 InetPton 将定义为此函数的 ANSI 版本 InetPtonA。此函数的 ANSI 版本始终定义为 inet_pton。 pszAddrString 参数定义为 PCSTR 数据类型。

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

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

在 Windows Vista 及更高版本上， RtlIpv4StringToAddress 和 RtlIpv4StringToAddressEx 函数可用于将 Internet 标准点十进制表示法中的 IPv4 地址的文本表示形式转换为表示为 IN_ADDR 结构的数字二进制地址。在 Windows Vista 及更高版本上， RtlIpv6StringToAddress 和 RtlIpv6StringToAddressEx 函数可用于将 IPv6 地址的字符串表示形式转换为表示为 IN6_ADDR 结构的数字二进制 IPv6 地址。 RtlIpv6StringToAddressEx 函数更灵活，因为它还会将 IPv6 地址的字符串表示形式转换为数字二进制形式，该地址可以包含范围 ID 和端口。

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

要求

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