If no error occurs, this function returns a value of type SOCKETthat is a descriptor for the newly created multipoint socket. If an error occurs, a value of INVALID_SOCKET is returned. A specific error code can be retrieved by calling WSAGetLastError.

On a blocking socket, the return value indicates success or failure of the join operation.

With a nonblocking socket, successful initiation of a join operation is indicated by a return of a valid socket descriptor. Subsequently, an FD_CONNECT indication will be given on the original socket swhen the join operation completes, either successfully or otherwise. The application must use WSAEventSelectwith interest registered for the FD_CONNECT event in order to determine when the join operation has completed. It then checks the associated error code to determine the success or failure of the operation. The selectfunction cannot be used to determine when the join operation completes. Also, until the multipoint session join attempt completes, all subsequent calls to WSAJoinLeafon the same socket will fail with the error code WSAEALREADY. After the WSAJoinLeafoperation completes successfully, a subsequent attempt will usually fail with the error code WSAEISCONN. An exception to the WSAEISCONN rule occurs for a c_rootsocket that allows root-initiated joins. In such a case, another join may be initiated after a prior WSAJoinLeafoperation completes.

If the return error code indicates that the multipoint session join attempt failed with error codes WSAECONNREFUSED, WSAENETUNREACH, or WSAETIMEDOUT, the application can call WSAJoinLeafagain for the same socket.

The following table shows the possible error values.

Note:
WSAJoinLeafis not supported for the default TCP/UDP provider and will always return WSASYSCALLFAILURE.

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.

The WSAJoinLeaffunction has the same parameters and semantics as WSAConnectexcept that it returns a socket descriptor (as in WSAAccept), and it has an additional dwFlagsparameter. Only multipoint sockets created using WSASocketwith the appropriate multipoint flags set can be used for input parameter sin this function. The returned socket descriptor will not be usable until after the join operation completes. For example, if the socket is in nonblocking mode after a corresponding FD_CONNECT indication has been received from WSAEventSelecton the original socket s, closesocketmay be invoked on this new socket descriptor to cancel a pending join operation. A root application in a multipoint session may call WSAJoinLeafone 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.

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 WSAEventSelect. 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 selectfunction cannot be used to detect completion notification for WSAJoinLeaf.

The socket descriptor returned by WSAJoinLeafis 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 nameparameter 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. The newly created socket has the same properties as s,including asynchronous events registered with WSAEventSelect. It is not intended to be used for the exchange of multipoint data, but rather it is used to receive network event indications such as FD_CLOSE for the connection that exists to the particular c_leaf. Some multipoint implementations can also allow this socket to be used for side chats between the root and an individual leaf node. An FD_CLOSE indication will be received for this socket if the corresponding leaf node calls closesocketto drop out of the multipoint session. Symmetrically, invoking closesocket on the c_leaf socket returned from WSAJoinLeafwill cause the socket in the corresponding leaf node to get an FD_CLOSE notification.

When WSAJoinLeafis invoked with a c_leaf socket, the nameparameter contains the address of the root application for a rooted control scheme, or an existing multipoint session for a nonrooted control scheme, and the returned socket descriptor is the same as the input socket descriptor. In other words, a new socket descriptor is not allocated. In a rooted control scheme, the root application would put its c_root socket in listening mode by calling listen. The standard FD_ACCEPT notification will be delivered when the leaf node requests to join itself to the multipoint session. The root application uses the usual accept/ WSAAcceptfunctions to admit the new leaf node. The value returned from either accept or WSAAcceptis also a c_leaf socket descriptor just like those returned from WSAJoinLeaf. 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 an input to WSAJoinLeaf.

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

The lpCallerDataparameter is 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 lpCalleeDataparameter is a result parameter that will contain any user data passed back from the peer as part of the multipoint session establishment. The lpCalleeData->leninitially contains the length of the buffer allocated by the application and pointed to by lpCalleeData->buf. lpCalleeData->lenwill be set to 0 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 WSAJoinLeaffunction returns. For nonblocking sockets, this will be after the join operation has completed. For example, this could occur after FD_CONNECT notification 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.

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

When connected sockets break or 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 application must discard and recreate the needed sockets in order to return to a stable point.