LPWSPCONNECT 回调函数 (ws2spi.h)

项目
08/28/2023

LPWSPConnect 函数与对等机建立连接，交换连接数据，并根据提供的流规范指定所需的服务质量。

语法

LPWSPCONNECT Lpwspconnect;

int Lpwspconnect(
  [in]  SOCKET s,
  [in]  const sockaddr *name,
  [in]  int namelen,
  [in]  LPWSABUF lpCallerData,
  [out] LPWSABUF lpCalleeData,
  [in]  LPQOS lpSQOS,
  [in]  LPQOS lpGQOS,
  [out] LPINT lpErrno
)
{...}

参数

[in] s

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

[in] name

sockaddr 中的套接字要连接到的对等方的名称。

[in] namelen

名称的长度（以字节为单位）。

[in] lpCallerData

指向在建立连接期间要传输到对等方的用户数据的指针。

[out] lpCalleeData

指向缓冲区的指针，可在其中复制建立连接期间从对等方接收的任何用户数据。

[in] lpSQOS

指向套接字的流规范的指针，每个方向各有一个。

[in] lpGQOS

保留。

[out] lpErrno

指向错误代码的指针。

返回值

如果未发生错误， LPWSPConnect 将返回零。否则，它将返回SOCKET_ERROR，并且 lpErrno 中提供了特定的错误代码。

在阻塞套接字上，返回值指示连接尝试成功或失败。如果返回错误代码指示连接尝试失败 (即 WSAECONNREFUSED、 WSAENETUNREACH、 WSAETIMEDOUT) 则 Winsock SPI 客户端可以为同一套接字再次调用 LPWSPConnect 。

错误代码	含义
WSAENETDOWN	网络子系统失败。
WSAEADDRINUSE	套接字的本地地址已在使用中，并且未将套接字标记为允许使用 SO_REUSEADDR 重用地址。此错误通常在绑定时发生，但如果绑定到涉及ADDR_ANY) 的部分通配符地址 (，并且需要在此函数时提交特定地址，则可能会延迟到此函数。
WSAEINTR	(阻止) 调用已通过 LPWSPCancelBlockingCall 取消。
WSAEINPROGRESS	阻止 Winsock 调用正在进行，或者服务提供商仍在处理回调函数。
WSAEALREADY	在指定的套接字上进行非阻止 LPWSPConnect 调用。为了保持向后兼容性，此错误以 WSAEINVAL 的形式报告给链接到 Winsock.dll 或 Wsock32.dll 的 Windows 套接字 1.1 应用程序。
WSAEADDRNOTAVAIL	远程地址不是有效的地址 (，例如，ADDR_ANY) 。
WSAEAFNOSUPPORT	指定系列中的地址无法与此套接字一起使用。
WSAECONNREFUSED	尝试连接被拒绝。
WSAEFAULT	name 或 namelen 参数不是用户地址空间的有效部分，namelen 参数太小，lpCalleeData、lpSQOS 和 lpGQOS 的缓冲区长度太小，或者 lpCallerData 的缓冲区长度太大。
WSAEINVAL	参数 s 是侦听套接字。
WSAEISCONN	套接字已 (面向连接的套接字仅) 连接。
WSAENETUNREACH	此时不可以从此主机访问该网络。
WSAENOBUFS	未提供任何缓冲区空间。无法连接套接字。
WSAENOTSOCK	：描述符不是套接字。
WSAEOPNOTSUPP	无法满足 lpSQOS 中指定的流规范。
WSAEPROTONOSUPPORT	服务提供商不支持 lpCallerData 扩充。
WSAETIMEDOUT	尝试连接超时，但未建立连接。
WSAEWOULDBLOCK	套接字标记为非阻止，连接无法立即完成。在使用 WSPSelect 函数进行连接时，可以使用 LPWSPSelect 函数选择套接字进行写入。
WSAEACCES	尝试将数据报套接字连接到广播地址失败，因为未启用 WSPSetSockOpt SO_BROADCAST。

注解

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

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

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

对于无连接套接字 (例如，SOCK_DGRAM) 类型， LPWSPConnect 执行的操作是建立默认目标地址，以便该套接字可以用于后续面向连接的发送和接收操作 (LPWSPSend、 LPWSPRecv) 。从指定的目标地址以外的地址接收的任何数据报将被丢弃。如果名称结构的地址成员全部为零，则套接字将断开连接 - 默认远程地址将不确定，因此 LPWSPSend 和 LPWSPRecv 调用将返回错误代码 WSAENOTCONN。但是，仍可使用 LPWSPSendTo 和 LPWSPRecvFrom 。只需再次调用 LPWSPConnect 即可更改默认目标，即使套接字已连接也是如此。如果名称与以前的 LPWSPConnect 不同，则放弃排队接收的任何数据报。

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

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

Winsock SPI 客户端负责分配它指定的任何参数直接或间接指向的任何内存空间。

lpCallerData 是一个值参数，其中包含要随连接请求一起发送的任何用户数据。如果 lpCallerData 为 null，则不会将用户数据传递给对等方。 lpCalleeData 是一个 result 参数，它将引用在建立连接过程中从对等方传回的任何用户数据。 lpCalleeData-len> 最初包含由 Winsock SPI 客户端分配并由 lpCalleeData-buf> 指向的缓冲区长度。如果未传回任何用户数据，则 lpCalleeData-len> 将设置为零。连接操作完成后， lpCalleeData 信息将有效。对于阻塞套接字，将在 LPWSPConnect 函数返回时返回。对于非阻止套接字，这将在发生FD_CONNECT通知之后。如果 lpCalleeData 为 null，则不会传回任何用户数据。用户数据的确切格式特定于套接字所属的地址系列和/或所涉及的应用程序。

在连接时，Winsock SPI 客户端可以使用 lpSQOS 参数通过 LPWSPIoctl 使用SIO_SET_QOS操作码替代针对套接字所做的任何以前的 QoS 规范。

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

注意

当连接的套接字中断 (也就是说，由于任何原因) 关闭时，应将其丢弃并重新创建。最安全的假设是，当由于任何原因在连接的套接字上发生故障时，Winsock SPI 客户端必须放弃并重新创建所需的套接字才能返回到稳定点。

要求

要求	值
最低受支持的客户端	Windows 2000 Professional [仅限桌面应用]
最低受支持的服务器	Windows 2000 Server [仅限桌面应用]
标头	ws2spi.h