WSAConnect 函数（winsock2.h）

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

Syntax

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

指向套接字的 QOS 结构的指针。

[in] lpGQOS

保留以供将来与套接字组一起使用。指向套接字组的 QOS 结构的指针（如果适用）。此参数应为 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	通过 WSACancelBlockingCall0 取消了套接字 1.1 调用（Windows 阻止） <。
WSAEINPROGRESS	正在阻止 Windows 套接字 1.1 调用，或者服务提供商仍在处理回调函数。
WSAEALREADY	指定的套接字上正在进行非阻止连接或 WSAConnect 调用。
WSAEADDRNOTAVAIL	远程地址不是有效的地址（如ADDR_ANY）。
WSAEAFNOSUPPORT	指定系列中的地址不能用于此套接字。
WSAECONNREFUSED	尝试连接被拒绝。
WSAEFAULT	名称或 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 函数用于创建与指定目标的连接，并执行连接时发生的许多其他辅助操作。如果套接字（s）未绑定，则系统将唯一值分配给本地关联，并且该套接字被标记为绑定。

对于面向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）。从指定的目标地址以外的地址接收的任何数据报将被丢弃。如果整个名称结构都是零（而不仅仅是名称结构的地址参数），则将断开套接字的连接。然后，默认远程地址将是不确定的，因此发送、WSASend、recv 和 WSARecv 调用将返回错误代码 WSAENOTCONN。但是，仍然可以使用 sendto、 WSASendTo、 recvfrom 和 WSARecvFrom 。只需再次调用 WSAConnect 即可更改默认目标，即使套接字已连接也是如此。如果名称与以前的 WSAConnect 不同，则丢弃排队接收的任何数据报。

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

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

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

lpCallerData 参数包含指向要随连接请求一起发送的任何用户数据的指针（称为连接数据）。这是额外的数据，而不是正常的网络数据流，与网络请求一起发送以建立连接。此选项由旧协议（如 DECNet、OSI TP4 等）使用。

Note 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 替代通过 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 值表示没有应用程序提供的组服务质量。如果 s 不是套接字组的创建者，则忽略此参数。

当连接套接字因任何原因而关闭时，应将其丢弃并重新创建。最安全的做法是，当连接套接字上出于任何原因而发生争吵时，应用程序必须放弃并重新创建所需的套接字，才能返回到稳定点。

注意发出阻止的 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 应用商店应用支持此函数。

要求

Requirement	价值
最低支持的客户端	Windows 8.1、Windows Vista [桌面应用 \|UWP 应用]
支持的最低服务器	Windows Server 2003 [桌面应用 \|UWP 应用]
目标平台	Windows操作系统
头	winsock2.h
库	Ws2_32.lib
DLL	Ws2_32.dll