Share via

LPWSPJOINLEAF 回调函数 (ws2spi.h)

  • 项目

WSPJoinLeaf 函数将叶节点加入多点会话，交换连接数据，并根据提供的流规范指定所需的服务质量。

语法

LPWSPJOINLEAF Lpwspjoinleaf;

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

参数

[in] s

标识多点套接字的描述符。

[in] name

sockaddr 结构中的套接字要联接到的对等方的名称。

[in] namelen

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

[in] lpCallerData

指向在建立多点会话期间要传输到对等方的用户数据的指针。

[out] lpCalleeData

指向在建立多点会话期间要从对等方传输回的用户数据的指针。

[in] lpSQOS

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

[in] lpGQOS

保留。

[in] dwFlags

指示套接字充当发送方和/或接收方的标志。

[out] lpErrno

指向错误代码的指针。

返回值

如果未发生错误， WSPJoinLeaf 将返回 SOCKET 类型的值，该值是新创建的多点套接字的描述符。 否则，将返回值 INVALID_SOCKET，并在 lpErrno 中提供特定的错误代码。

在阻塞套接字上，返回值指示联接操作成功或失败。

使用非阻止套接字时，联接操作的成功启动由有效套接字描述符的返回值指示。 随后，当联接操作成功或以其他方式完成时，会给出FD_CONNECT指示。 与FD_CONNECT关联的错误代码指示 WSPJoinLeaf 是成功还是失败。

此外，在多点会话联接尝试完成对同一套接字上的 WSPJoinLeaf 的所有后续调用之前，将失败并显示错误代码 WSAEALREADY。 在 WSPJoinLeaf 成功完成后，后续尝试通常会失败，并显示错误代码 WSAEISCONN。 对于允许根发起的联接的c_root套接字，WSAEISCONN 规则将发生异常。 在这种情况下，在之前的 WSPJoinLeaf 完成后，可能会启动另一个联接。

如果返回错误代码指示多点会话联接尝试失败 (即 WSAECONNREFUSED、 WSAENETUNREACH、 WSAETIMEDOUT) Windows 套接字 SPI 客户端可以为同一套接字再次调用 WSPJoinLeaf 。

错误代码 含义
WSAENETDOWN
 网络子系统失败。
WSAEADDRINUSE
 套接字的本地地址已在使用中，并且未将套接字标记为允许通过SO_REUSEADDR重复使用地址。 此错误通常在绑定时发生，但如果**bind** 是涉及ADDR_ANY) 的部分野生卡地址 (，并且需要在此函数时“提交”特定地址，则可能会延迟到此函数。
WSAEINTR
 (阻止) 调用已通过 WSPCancelBlockingCall 取消。
WSAEINPROGRESS
 正在阻止 Windows 套接字调用，或者服务提供程序仍在处理回调函数。
WSAEALREADY
 在指定的套接字上进行非阻止 WSPJoinLeaf 调用。
WSAEADDRNOTAVAIL
 远程地址不是有效的地址 (，例如，ADDR_ANY) 。
WSAEAFNOSUPPORT
 指定系列中的地址无法与此套接字一起使用。
WSAECONNREFUSED
 试图加入被强行拒绝。
WSAEFAULT
 name 或 namelen 参数不是用户地址空间的有效部分，namelen 参数太小，lpCalleeData、lpSQOS 和 lpGQOS 的缓冲区长度太小，或者 lpCallerData 的缓冲区长度太大。
WSAEISCONN
 套接字已是多点会话的成员。
WSAENETUNREACH
 此时不可以从此主机访问该网络。
WSAENOBUFS
 未提供任何缓冲区空间。 无法联接套接字。
WSAENOTSOCK
 ：描述符不是套接字。
WSAEOPNOTSUPP
 无法满足 lpSQOS 中指定的流规范。
WSAEPROTONOSUPPORT
 服务提供商不支持 lpCallerData 扩充。
WSAETIMEDOUT
 未建立多点会话的加入尝试超时。
 
 

备注

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

WSPJoinLeaf 具有与 LPWSPConnect 相同的参数和语义，只不过它返回的套接字描述符 (与 LPWSPAccept) 中一样，并且具有额外的 dwFlags 参数。 只有使用设置了适当多点标志的 LPWSPSocket 创建的多点套接字才能用于此 函数中的输入 参数 。 如果套接字处于非阻止模式，则在收到原始套接字 上的相应FD_CONNECT指示之前，返回 的 套接字描述符将不可用，但可在此新套接字描述符上调用 closesocket 以取消挂起的联接操作。 多点会话中的根节点可以调用 WSPJoinLeaf 一次或多次以添加多个叶节点，但一次最多只能有一个多点连接请求未完成。 有关其他信息，请参阅 SPI 中的独立于协议的多播和多点 。

对于非阻塞套接字，通常无法立即完成连接。 在这种情况下，此函数返回一个尚不可用的套接字描述符，并且操作继续进行。 在这种情况下，没有类似于 WSAEWOULDBLOCK 的错误代码，因为函数实际上已返回“成功启动”指示。 当最终结果成功或失败已知时，可以通过 LPWSPAsyncSelect 或 LPWSPEventSelect 进行报告，具体取决于客户端在 原始套接字上注册通知的方式。 在任一情况下，通知都以FD_CONNECT播报，并且与FD_CONNECT关联的错误代码指示成功或失败的特定原因。 请注意， LPWSPSelect 不能用于检测 WSPJoinLeaf 的完成通知。

WSPJoinLeaf 返回的套接字描述符会有所不同，具体取决于输入套接字描述符 s 是c_root还是c_leaf。 与 c_root 套接字一起使用时， name 参数指定要添加的特定叶节点，并且返回的套接字描述符是对应于新添加的叶节点的c_leaf套接字。 (如 描述符分配部分中所述，分配新的套接字描述符时，IFS 提供程序必须调用 WPUModifyIFSHandle ，非 IFS 提供程序必须调用 WPUCreateSocketHandle) 。 新创建的套接字具有与 相同的属性 ， 包括向 LPWSPAsyncSelect 或 LPWSPEventSelect 注册的异步事件。 它不用于交换多点数据，而是用于接收网络事件指示 (例如，FD_CLOSE) 与特定c_leaf的连接。 某些多点实现还允许将此套接字用于根节点和单个叶节点之间的“旁聊天”。 如果相应的叶节点调用 LPWSPCloseSocket 退出多点会话，则会收到此套接字的FD_CLOSE指示。 对称地，在从 WSPJoinLeaf 返回的c_leaf套接字上调用 WSPCloseSocket 将导致相应叶节点中的套接字收到FD_CLOSE通知。

使用c_leaf套接字调用 WSPJoinLeaf 时， name 参数包含根控制方案 (的地址) 或现有多点会话 (非根控制方案) ，返回的套接字描述符与输入套接字描述符相同。 换句话说，不会分配新的套接字描述符。 在根控制方案中，根应用程序会通过调用 LPWSPListen 将其c_root套接字置于侦听模式。 当叶节点请求将自身加入多点会话时，将传递标准FD_ACCEPT通知。 根应用程序使用常用的 LPWSPAccept 函数来允许新的叶节点。 从 WSPAccept 返回的值也是c_leaf套接字描述符，就像从 WSPJoinLeaf 返回的值一样。 为了适应同时允许根发起联接和叶发起联接的多点方案，可以接受已处于侦听模式的c_root套接字用作 WSPJoinLeaf 的输入。

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

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

在多点会话建立时，Windows 套接字 SPI 客户端可以使用 lpSQOS 参数来替代以前通过 LPWSPIoctl 使用 SIO_SET_QOS opcode 为套接字制定的任何 QoS 规范。

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

dwFlags 参数用于指示套接字是仅充当发送方 (JL_SENDER_ONLY) ，还是仅充当接收方 (JL_RECEIVER_ONLY) ，还是同时充当两者 (JL_BOTH) 。

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

要求

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

另请参阅

LPWSPAccept

LPWSPAsyncSelect

LPWSPBind

LPWSPEventSelect

LPWSPSelect

LPWSPSocket