WSAConnect 函数 (winsock2.h)

项目
08/27/2023

WSAConnect 函数与另一个套接字应用程序建立连接，交换连接数据，并根据指定的 FLOWSPEC 结构指定所需的服务质量。

语法

int WSAAPI WSAConnect(
  [in]  SOCKET         s,
  [in]  const sockaddr *name,
  [in]  int            namelen,
  [in]  LPWSABUF       lpCallerData,
  [out] LPWSABUF       lpCalleeData,
  [in]  LPQOS          lpSQOS,
  [in]  LPQOS          lpGQOS
);

参数

[in] s

标识未连接的套接字的描述符。

[in] name

指向 sockaddr 结构的指针，该结构指定要连接到的地址。对于 IPv4，sockaddr 包含地址系列、目标 IPv4 地址和目标端口的AF_INET。对于 IPv6，sockaddr 结构包含地址系列、目标 IPv6 地址、目标端口 的AF_INET6 ，并且可能包含其他流和范围 ID 信息。

[in] namelen

name 参数指向的 sockaddr 结构的长度（以字节为单位）。

[in] lpCallerData

指向在建立连接期间要传输到另一个套接字的用户数据的指针。请参阅“备注”。

[out] lpCalleeData

指向在建立连接期间要从另一个套接字传输回的用户数据的指针。请参阅“备注”。

[in] lpSQOS

指向套接字的FLOWSPEC 结构的指针，每个方向各一个。

[in] lpGQOS

保留以供将来与套接字组一起使用。指向套接字组的 FLOWSPEC 结构的指针 (（如果适用) ）。此参数应为 NULL。

返回值

如果未发生错误， 则 WSAConnect 返回零。否则，它将返回SOCKET_ERROR，并且可以通过调用 WSAGetLastError 来检索特定的错误代码。在阻止套接字上，返回值指示连接尝试成功或失败。

使用非阻止套接字时，无法立即完成连接尝试。在这种情况下， WSAConnect 将返回 SOCKET_ERROR，WSAGetLastError 将返回 WSAEWOULDBLOCK;因此，应用程序可以：

使用 select 通过检查套接字是否可写来确定连接请求的完成情况。
如果应用程序使用 WSAAsyncSelect 来指示对连接事件感兴趣，则在连接操作完成 (成功或不) 时，应用程序将收到FD_CONNECT通知。
如果应用程序使用 WSAEventSelect 来指示对连接事件的兴趣，则在连接操作完成 (成功或不) 时，将向关联的事件对象发出信号。

对于非阻止套接字，在连接尝试完成对同一套接字上的 WSAConnect 的所有后续调用之前，将失败并显示错误代码 WSAEALREADY。

如果返回错误代码指示连接尝试失败 (即 WSAECONNREFUSED、 WSAENETUNREACH、 WSAETIMEDOUT) 应用程序可以为同一套接字再次调用 WSAConnect 。

错误代码	含义
WSANOTINITIALIZED	在使用此函数之前，必须成功调用 WSAStartup 。
WSAENETDOWN	网络子系统发生故障。
WSAEADDRINUSE	套接字的本地地址已在使用中，并且未将套接字标记为允许使用 SO_REUSEADDR 重用地址。此错误通常在绑定执行期间发生，但如果绑定函数对涉及ADDR_ANY) 的部分通配符地址 (操作，并且需要在此函数时“提交”特定地址，则可能会延迟到此函数。
WSAEINTR	(阻止) Windows 套接字 1.1 调用已通过 WSACancelBlockingCall 取消。
WSAEINPROGRESS	阻止 Windows 套接字 1.1 调用正在进行，或者服务提供商仍在处理回调函数。
WSAEALREADY	在指定的套接字上正在进行非阻止连接或 WSAConnect 调用。
WSAEADDRNOTAVAIL	远程地址不是有效的地址 (，例如ADDR_ANY) 。
WSAEAFNOSUPPORT	指定系列中的地址无法与此套接字一起使用。
WSAECONNREFUSED	：连接尝试被拒绝。
WSAEFAULT	name 或 namelen 参数不是用户地址空间的有效部分，namelen 参数太小，lpCalleeData、lpSQOS 和 lpGQOS 的缓冲区长度太小，或者 lpCallerData 的缓冲区长度太大。
WSAEINVAL	参数是侦听套接字，或者指定的目标地址与套接字所属的约束组的目标地址不一致，或者 lpGQOS 参数不是 NULL。
WSAEISCONN	仅) (面向连接的套接字已连接套接字。
WSAENETUNREACH	此时不可以从此主机访问该网络。
WSAEHOSTUNREACH	套接字操作尝试访问无法访问的主机。
WSAENOBUFS	未提供任何缓冲区空间。无法连接套接字。
WSAENOTSOCK	：描述符不是套接字。
WSAEOPNOTSUPP	无法满足 lpSQOS 和 lpGQOS 中指定的 FLOWSPEC 结构。
WSAEPROTONOSUPPORT	服务提供商不支持 lpCallerData 参数。
WSAETIMEDOUT	：连接尝试超时，没有建立连接。
WSAEWOULDBLOCK	：套接字标记为非阻止，无法立即完成连接。
WSAEACCES	尝试将数据报套接字连接到广播地址失败，因为未启用 setsockopt SO_BROADCAST。

注解

WSAConnect 函数用于创建与指定目标的连接，并执行在连接时发生的许多其他辅助操作。如果套接字未绑定，系统会将唯一值分配给本地关联，并将套接字标记为绑定。

对于面向 Windows Vista 及更高版本的应用程序，请考虑使用 WSAConnectByList 或 WSAConnectByName 函数，以大大简化客户端应用程序设计。

例如，对于面向连接的套接字 (类型SOCK_STREAM) ，将使用名称 (套接字命名空间中的地址启动到外部主机的活动连接;有关详细说明，请参阅绑定) 。此调用成功完成后，套接字已准备好发送/接收数据。如果名称结构的地址参数全部为零， 则 WSAConnect 将返回错误 WSAEADDRNOTAVAIL。任何重新连接尝试都将失败，错误代码为 WSAEISCONN。

注意如果打开套接字，进行 setsockopt 调用，然后进行 sendto 调用，Windows 套接字将执行隐式绑定函数调用。

对于面向连接的非阻塞套接字，通常无法立即完成连接。在这种情况下，此函数返回错误 WSAEWOULDBLOCK。但是，操作会继续。当成功或失败结果已知时，可以通过多种方式之一报告它，具体取决于客户端注册通知的方式。如果客户端使用 select，则会在 writefd 集中报告成功，在 exceptfds 集中报告失败。如果客户端使用 WSAAsyncSelect 或 WSAEventSelect，则通知会FD_CONNECT，并且与FD_CONNECT关联的错误代码指示成功或失败的特定原因。

例如，对于无连接套接字 (类型 SOCK_DGRAM) ，WSAConnect 执行的操作只是为了建立默认目标地址，以便该套接字可用于后续面向连接的发送和接收操作， (send、 WSASend、 recv 和 WSARecv) 。将从指定的目标地址以外的地址接收的任何数据报将被丢弃。如果整个名称结构都是零 (而不仅仅是名称结构) 的地址参数，则套接字将断开连接。然后，默认远程地址将不确定，因此 send、 WSASend、 recv 和 WSARecv 调用将返回错误代码 WSAENOTCONN。但是，仍然可以使用 sendto、 WSASendTo、 recvfrom 和 WSARecvFrom 。只需再次调用 WSAConnect 即可更改默认目标，即使套接字已连接。如果名称与以前的 WSAConnect 不同，则放弃任何排队接收的数据报。

对于无连接套接字，名称可以指示任何有效的地址，包括广播地址。但是，若要连接到广播地址，套接字必须启用 setsockopt SO_BROADCAST。否则， WSAConnect 将失败，错误代码为 WSAEACCES。

在无连接套接字上，无法交换用户到用户的数据，相应的参数将以无提示方式忽略。

应用程序负责分配它指定的任何参数直接或间接指向的任何内存空间。

lpCallerData 参数包含指向要随连接请求一起发送的任何用户数据的指针， (称为连接数据) 。这是附加数据，不在正常网络数据流中，是随网络请求一起发送的，用于建立连接。旧版协议（如 DECNet、OSI TP4 等）使用此选项。

注意 Windows 中的 TCP/IP 协议不支持连接数据。仅 ATM (RAWWAN) 通过原始套接字支持连接数据。

如果 lpCallerData 为 NULL，则不会将用户数据传递给对等方。 lpCalleeData 是一个结果参数，它将包含作为 WSABUF 结构中建立连接的一部分从另一个套接字传回的任何用户数据。 lpCalleeData 参数指向的 WSABUF 结构的 len 成员最初包含应用程序为 WSABUF 结构的 buf 成员分配的缓冲区长度。如果未传回任何用户数据，则 lpCalleeData 参数指向的 WSABUF 结构的 len 成员将设置为零。连接操作完成后， lpCalleeData 信息将有效。对于阻塞套接字，连接操作在 WSAConnect 函数返回时完成。对于非阻止套接字，将在发生FD_CONNECT通知后完成。如果 lpCalleeData 为 NULL，则不会传回任何用户数据。用户数据的确切格式特定于套接字所属的地址系列。

在连接时，应用程序可以使用 lpSQOS 和 lpGQOS 参数通过 WSAIoctl 使用SIO_SET_QOS或SIO_SET_GROUP_QOS操作码替代以前为套接字所做的任何服务质量规范。

lpSQOS 参数指定套接字的FLOWSPEC 结构，每个方向一个，后跟任何其他提供程序特定的参数。如果关联的传输提供程序通常或特定类型的套接字无法遵循服务质量请求，将返回错误，如下所述。对于任何单向套接字，将分别忽略发送或接收流规范值。如果未指定特定于提供程序的参数，则 lpCalleeData 参数指向的 WSABUF 结构的 buf 和 len 成员应分别设置为 NULL 和零。 lpSQOS 参数的 NULL 值表示没有应用程序提供的服务质量。

保留供将来用于套接字组 lpGQOS 指定套接字组 (的 FLOWSPEC 结构（如果适用），) ，每个方向各一个，后跟任何其他特定于提供程序的参数。如果未指定特定于提供程序的参数，则 lpCalleeData 参数指向的 WSABUF 结构的 buf 和 len 成员应分别设置为 NULL 和零。 lpGQOS 的 NULL 值表示没有应用程序提供的组服务质量。 如果不是套接字组的创建者，则将忽略此参数。

当连接的套接字因任何原因而关闭时，应将其丢弃并重新创建。最安全的假设是，当连接套接字由于任何原因而出现问题时，应用程序必须放弃并重新创建所需的套接字，以便返回到稳定点。

注意发出阻止 Winsock 调用（如 WSAConnect）时，Winsock 可能需要等待网络事件，然后调用才能完成。在这种情况下，Winsock 执行可发出警报的等待， (在同一线程上计划的 APC) 异步过程调用可能会中断该等待。在 APC 内发出另一个阻止 Winsock 调用，该调用中断了同一线程上正在进行的阻止 Winsock 调用将导致未定义的行为，并且 Winsock 客户端绝不能尝试。

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

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

要求

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