WSHJoinLeaf

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
        );

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

Parameters

HelperDllSocketContext

Points to a per-socket context area, allocated and initialized by the WSH DLL WSHOpenSocket or WSHOpenSocket2 function.

SocketHandle

Specifies the handle to the socket that was used to establish a multipoint session.

TdiAddressObjectHandle

Specifies the handle to a file object representing the open transport address for the socket. 

TdiConnectionObjectHandle

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

Points 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

Specifies the handle to the newly created socket that is being added to the multipoint session.

Sockaddr

Points to the value from WSAJoinLeaf for the name of the peer socket with which the leaf will be merged.

SockaddrLength

Specifies the length in bytes at Sockaddr.

CallerData

Points to a buffer containing data that should be transmitted to the peer socket when the sockets are joined.

CalleeData

Points to a buffer in which WSAJoinLeaf returns any data transmitted by the peer socket when the sockets are joined.

SocketQOS

Points 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

Points to a quality-of-service 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

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 (see Comments) corresponding to a Windows Sockets error code, defined in winsock2.h.

Comments

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 nonNULL, 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.

See Also

WSHOpenSocket2