As mentioned previously, WSPJoinLeaf is used to join a leaf node into a multipoint session. WSPJoinLeaf has the same parameters and semantics as WSPConnect except that it returns a socket descriptor (as in WSPAccept), and it has an additional dwFlags parameter. The dwFlags parameter is used to indicate whether the socket will be acting only as a sender, only as a receiver, or both. Only multipoint sockets may be used for input parameter s in this function. If the multipoint socket is in the non-blocking mode, the returned socket descriptor will not be useable until after a corresponding FD_CONNECT indication has been received. A root application in a multipoint session may call WSPJoinLeaf one or more times in order to add a number of leaf nodes, however at most one multipoint connection request may be outstanding at a time.
The socket descriptor returned by WSPJoinLeaf is different depending on whether the input socket descriptor, s, is a c_root or a c_leaf. When used with a c_root socket, the name parameter designates a particular leaf node to be added and the returned socket descriptor is a c_leaf socket corresponding to the newly added leaf node. It is not intended to be used for exchange of multipoint data, but rather is used to receive network event indications (e.g. FD_CLOSE) for the connection that exists to the particular c_leaf. Some multipoint implementations may also allow this socket to be used for "side chats" between the root and an individual leaf node. An FD_CLOSE indication should be given for this socket if the corresponding leaf node calls WSPCloseSocket to drop out of the multipoint session. Symmetrically, invoking WSPClosesocket on the c_leaf socket returned from WSPJoinLeaf will cause the socket in the corresponding leaf node to get FD_CLOSE notification.
When WSPJoinLeaf is invoked with a c_leaf socket, the name parameter contains the address of the root application (for a rooted control scheme) or an existing multipoint session (non-rooted control scheme), and the returned socket descriptor is the same as the input socket descriptor. In a rooted control scheme, the root client would put its c_root socket in the listening mode by calling WSPListen. The standard FD_ACCEPT notification will be delivered when the leaf node requests to join itself to the multipoint session. The root client uses the usual WSPAccept function to admit the new leaf node. The value returned from WSPAccept is also a c_leaf socket descriptor just like those returned from WSPJoinLeaf. To accommodate multipoint schemes that allow both root-initiated and leaf-initiated joins, it is acceptable for a c_root socket that is already in listening mode to be used as in input to WSPJoinLeaf.
A multipoint root client is generally responsible for the orderly dismantling of a multipoint session. Such an application may use WSPShutdown or WSPClosesocket on a c_root socket to cause all of the associated c_leaf sockets, including those returned from WSPJoinLeaf and their corresponding c_leaf sockets in the remote leaf nodes, to get FD_CLOSE notification.