WSAStringToAddressA 函数 (winsock2.h)

项目
08/27/2023

WSAStringToAddress 函数将标准文本表示形式的网络地址转换为 sockaddr 结构中的数字二进制形式，适合传递给采用此类结构的 Windows 套接字例程。

语法

INT WSAAPI WSAStringToAddressA(
  [in]           LPSTR               AddressString,
  [in]           INT                 AddressFamily,
  [in, optional] LPWSAPROTOCOL_INFOA lpProtocolInfo,
  [out]          LPSOCKADDR          lpAddress,
  [in, out]      LPINT               lpAddressLength
);

参数

[in] AddressString

指向以零结尾的字符串的指针，该字符串包含要转换的标准文本形式的网络地址。

[in] AddressFamily

AddressString 参数指向的网络地址的地址系列。

[in, optional] lpProtocolInfo

与要使用的提供程序关联的 WSAPROTOCOL_INFO 结构。如果为 NULL，则呼叫将路由到支持指定 AddressFamily 的第一个协议的提供程序。

[out] lpAddress

指向缓冲区的指针，如果函数成功，则为地址字符串填充 sockaddr 结构。

[in, out] lpAddressLength

指向 lpAddress 参数指向的缓冲区的长度（以字节为单位）的指针。如果函数调用成功，此参数将返回指向 lpAddress 参数中返回的 sockaddr 结构大小的指针。如果指定的缓冲区不够大，函数将失败并出现 WSAEFAULT 的特定错误，并且此参数将更新为所需的大小（以字节为单位）。

返回值

如果操作成功， 则 WSAStringToAddress 的 返回值为零。否则，将返回值 SOCKET_ERROR，并且可以通过调用 WSAGetLastError 来检索特定的错误号。

错误代码	含义
WSAEFAULT	lpAddress 参数指向的缓冲区太小。传入更大的缓冲区。
WSAEINVAL	函数无法将字符串转换为 sockaddr。有关详细信息，请参阅以下“备注”部分。
WSANOTINITIALISED	尚未初始化 WS2_32.DLL。应用程序必须先调用 WSAStartup，然后才能调用任何 Windows 套接字函数。
WSA_NOT_ENOUGH_MEMORY	内存不足，无法执行该操作。

注解

WSAStringToAddress 函数将标准文本形式的网络地址转换为 sockaddr 结构中的数字二进制形式。

如果可能，地址的任何缺失组件都将默认为合理的值。例如，缺少的端口号将默认为零。如果调用方希望由特定提供程序完成转换，则应在 lpProtocolInfo 参数中提供相应的WSAPROTOCOL_INFO结构。

如果 SOCKADDR_IN 结构的sin_family 成员（以 sockaddr 结构的形式传入 lpAddress 参数中）未设置为 AF_INET 或 AF_INET6，则 WSAStringToAddress 函数 (失败并返回 WSAEINVAL) 。

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

Windows Phone 8：Windows Phone 8 及更高版本上的 Windows Phone 应用商店应用支持此函数。

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

注意

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

要求


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