WSHJoinLeaf function

[ This function is obsolete for Windows Server 2003, Windows Vista, and later, and is no longer supported. ]

The WSHJoinLeaf function performs any protocol-specific actions that must be taken to add a socket to a multipoint session as a leaf node.

Syntax

INT WSHJoinLeaf(
  _In_ PVOID     HelperDllSocketContext,
  _In_ SOCKET    SocketHandle,
  _In_ HANDLE    TdiAddressObjectHandle,
  _In_ HANDLE    TdiConnectionObjectHandle,
  _In_ PVOID     LeafHelperDllSocketContext,
  _In_ SOCKET    LeafSocketHandle,
  _In_ PSOCKADDR Sockaddr,
  _In_ DWORD     SockaddrLength,
  _In_ LPWSABUF  CallerData,
  _In_ LPWSABUF  CalleeData,
  _In_ LPQOS     SocketQOS,
  _In_ LPQOS     GroupQOS,
  _In_ DWORD     Flags
);

Parameters

• HelperDllSocketContext [in]
  Pointer to a per-socket context area, allocated and initialized by the WSH DLL WSHOpenSocket or WSHOpenSocket2 function.

• SocketHandle [in]
  Specifies the handle to the socket that was used to establish a multipoint session.

• TdiAddressObjectHandle [in]
  Specifies the handle to a file object representing the open transport address for the socket.

• TdiConnectionObjectHandle [in]
  Specifies the handle to a file object representing the connection endpoint associated with the socket. If the socket is not currently connected, this parameter is NULL.

• LeafHelperDllSocketContext [in]
  Pointer to a helper DLL-defined socket context for a newly created socket (created by WSHOpenSocket2) that is being added as a new leaf node on the multipoint session.

• LeafSocketHandle [in]
  Specifies the handle to the newly created socket that is being added to the multipoint session.

• Sockaddr [in]
  Pointer to the value from WSAJoinLeaf for the name of the peer socket with which the leaf will be merged.

• SockaddrLength [in]
  Specifies the length in bytes at Sockaddr.

• CallerData [in]
  Pointer to a buffer containing data that should be transmitted to the peer socket when the sockets are joined.

• CalleeData [in]
  Pointer to a buffer in which WSAJoinLeaf returns any data transmitted by the peer socket when the sockets are joined.

• SocketQOS [in]
  Pointer to a quality-of-service flow specification for the multipoint session of the original socket as specified by the given SocketHandle. This parameter specifies quality of service for each direction of data.

• GroupQOS [in]
  Pointer to a quality-of-service (Qos) flow specification for the socket group. This specification cannot be used to change the QoS of the socket group, but can be used to modify the newly joined socket's QoS as part of that group.

• Flags [in]
  Specifies whether the socket being created as a new leaf node acts as a sender, receiver, or both as one of the following:

  • JL_SENDER_ONLY
    The new leaf node will act as a sender of data only.

  • JL_RECEIVER_ONLY
    The new leaf node will act as a receiver of data only

  • JL_BOTH
    The new leaf node will act as both a sender and receiver of data.

Return value

WSHJoinLeaf returns zero if the input parameters are valid and the function successful. Otherwise, it returns a nonzero value corresponding to a Windows Sockets error code, defined in winsock2.h.

Remarks

WSHJoinLeaf is responsible for performing any protocol-specific actions required to add a new socket to a multipoint session, including verifying parameters for applicability to the protocol being supported. WSHJoinLeaf must verify all parameters because no parameter checking is done between the call to WSAJoinLeaf and WSHJoinLeaf.

When the multipoint session is established, the helper DLL should transmit any data specified at CallerData to the peer-level socket when the connection is made. Any data returned by the peer socket should be copied into the buffer at CalleeData. If the protocol does not support the transmission of caller-supplied data and CallerData is non-NULL, the helper DLL should return WSAEPROTONOSUPPORT.

If the buffer sizes for CalleeData, SocketQOS, or GroupQOS are too small, then the error WSAEFAULT should be returned.

If a quality-of-service specification is provided at SocketQOS or GroupQOS but quality of service is not supported by the protocol, WSAEOPNOTSUPP should be returned. This error should also be returned if the given quality of service specification(s) cannot be met.

If an attempt to allocate memory to complete the join request fails, WSHJoinLeaf should return WSAENOBUFS to indicate that a low memory condition exists.

Requirements

Target platform	Desktop
Header	Wsahelp.h (include Wsahelp.h)

See also

WSHOpenSocket2

 

 

Send comments about this topic to Microsoft