WSAAddressToStringA 函数 (winsock2.h)

项目
03/13/2024

WSAAddressToString 函数将 sockaddr 结构的所有组件转换为地址的可读字符串表示形式。

这主要用于显示目的。如果调用方要求由特定提供程序执行转换，则应在 lpProtocolInfo 参数中提供相应的WSAPROTOCOL_INFO结构。

语法

INT WSAAPI WSAAddressToStringA(
  [in]           LPSOCKADDR          lpsaAddress,
  [in]           DWORD               dwAddressLength,
  [in, optional] LPWSAPROTOCOL_INFOA lpProtocolInfo,
  [in, out]      LPSTR               lpszAddressString,
  [in, out]      LPDWORD             lpdwAddressStringLength
);

参数

[in] lpsaAddress

指向要转换为字符串的 sockaddr 结构的指针。

[in] dwAddressLength

lpsaAddress 参数指向的 sockaddr 结构中地址的长度（以字节为单位）。 dwAddressLength 参数的大小可能因协议而异。

[in, optional] lpProtocolInfo

指向特定提供程序 WSAPROTOCOL_INFO 结构的指针。如果 is 参数为 NULL，则调用将路由到支持 lpsaAddress 参数中指示的地址系列的第一个协议的提供程序。

[in, out] lpszAddressString

指向接收人类可读地址字符串的缓冲区的指针。

[in, out] lpdwAddressStringLength

输入时，此参数指定 lpszAddressString 参数指向的缓冲区的长度。 ANSI 字符串的长度以字节表示，Unicode 字符串的长度以 WCHAR 表示。输出时，此参数返回字符串的长度，包括实际复制到 lpszAddressString 参数指向的缓冲区中的 NULL 终止符。如果指定的缓冲区不够大，函数将失败并出现 WSAEFAULT 的特定错误，并且此参数将更新为所需的大小。

返回值

如果未发生错误， WSAAddressToString 将返回零值。否则，将返回值 SOCKET_ERROR，并且可以通过调用 WSAGetLastError 来检索特定的错误号。

错误代码	含义
WSAEFAULT	指定的 lpcsAddress、 lpProtocolInfo 和 lpszAddressString 参数指向并非全部位于进程的地址空间中的内存，或者 lpszAddressString 参数指向的缓冲区太小。传入更大的缓冲区。
WSAEINVAL	传递的参数无效。如果 lpsaAddress、 dwAddressLength 或 lpdwAddressStringLength 参数为 NULL，则返回此错误。如果指定的地址不是有效的套接字地址，或者没有传输提供程序支持指定的地址系列，则也会返回此错误。
WSAENOBUFS	未提供任何缓冲区空间。
WSANOTINITIALISED	尚未初始化 Winsock 2 DLL。应用程序必须先调用 WSAStartup，然后才能调用任何 Windows 套接字函数。

注解

WSAAddressToString 函数提供与协议无关的地址到字符串转换。 WSAAddressToString 函数采用 lpsaAddress 参数指向的套接字地址结构，并返回指向以 NULL 结尾的字符串的指针，该字符串表示 lpszAddressString 参数中的套接字地址。虽然 inet_ntoa 函数仅适用于 IPv4 地址，但 WSAAddressToString 函数适用于本地计算机上的 Winsock 提供程序支持的任何套接字地址，包括 IPv6 地址。

如果 lpsaAddress 参数指向 IPv4 套接字地址， (地址系列 AF_INET) ，则 lpszAddressString 参数指向的缓冲区中返回的地址字符串采用点十进制表示法，如“192.168.16.0”中所示，这是以点数表示法表示的 IPv4 地址的示例。

如果 lpsaAddress 参数指向 IPv6 套接字地址 (地址系列 AF_INET6) ，则 lpszAddressString 参数指向的缓冲区中返回的地址字符串采用 Internet 标准格式。基本字符串表示形式由 8 个用冒号分隔的十六进制数字组成。由连续零数字的字符串替换为双冒号。 IPv6 地址的字符串表示形式中只能有一个双冒号。

如果 lpszAddressString 参数指向的缓冲区长度不足以接收套接字地址的字符串表示形式， 则 WSAAddressToString 返回 WSAEFAULT。

在 Windows XP 上添加了对使用 WSAAddressToString 函数的 IPv6 地址的支持，Service Pack 1 (SP1) 及更高版本。还必须在本地计算机上安装 IPv6，以便 WSAAddressToString 函数支持 IPv6 地址。

Windows Phone 8：Windows Phone 8 及更高版本上的 Windows Phone Store 应用支持 WSAAddressToStringW 函数。

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

注意

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

要求

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