This function always returns SOCKET_ERROR and sets lpErrnoto WSASYSCALLFAILURE on Windows Embedded CE.

This function is used to join a leaf node to a multipoint session, and to perform a number of other ancillary operations that occur at session join time as well. If the socket, s, is unbound, unique values are assigned to the local association by the system, and the socket is marked as bound.

This function has the same parameters and semantics as WSPConnectexcept that it returns a socket descriptor (as in WSPAccept), and it has an additional dwFlagsparameter. Only multipoint sockets created using WSPSocketwith appropriate multipoint flags set can be used for input parameter sin this function. If the socket is in the nonblocking mode, the returned socket descriptor will notbe useable until after a corresponding FD_CONNECT indication on the original socket shas been received, except that closesocketcan be invoked on this new socket descriptor to cancel a pending join operation. A root node in a multipoint session can call WSPJoinLeafone or more times in order to add a number of leaf nodes, however at most one multipoint connection request can be outstanding at a time.

For nonblocking sockets it is often not possible to complete the connection immediately. In such a case, this function returns an as-yet unusable socket descriptor and the operation proceeds. There is no error code such as WSAEWOULDBLOCK in this case, because the function has effectively returned a "successful start" indication. When the final outcome success or failure becomes known, it may be reported through WSPEventSelectdepending on how the client registers for notification on the original socket s. In either case, the notification is announced with FD_CONNECT and the error code associated with the FD_CONNECT indicates either success or a specific reason for failure.

The Windows Sockets SPI client is responsible for allocating any memory space pointed to directly or indirectly by any of the parameters it specifies.

The lpCallerDatais a value parameter that contains any user data that is to be sent along with the multipoint session join request. If lpCallerDatais NULL, no user data will be passed to the peer. The lpCalleeDatais a result parameter that will contain any user data passed back from the peer as part of the multipoint session establishment. lpCalleeData->leninitially contains the length of the buffer allocated by the Windows Sockets SPI client and pointed to by lpCalleeData->buf. lpCalleeData->lenwill be set to zero if no user data has been passed back. The lpCalleeDatainformation will be valid when the multipoint join operation is complete. For blocking sockets, this will be when the WSPJoinLeaffunction returns. For nonblocking sockets, this will be after the FD_CONNECT notification has occurred on the original socket s. If lpCalleeDatais NULL, no user data will be passed back. The exact format of the user data is specific to the address family to which the socket belongs and/or the applications involved.

The dwFlagsparameter is used to indicate whether the socket will be acting only as a sender (JL_SENDER_ONLY), only as a receiver (JL_RECEIVER_ONLY), or both (JL_BOTH).

Note:
When connected sockets break (that is, become closed for whatever reason), they should be discarded and recreated. It is safest to assume that when things go awry for any reason on a connected socket, the Windows Sockets SPI client must discard and recreate the needed sockets in order to return to a stable point.