WSAJoinLeaf function

The WSAJoinLeaf function joins a leaf node into a multipoint session, exchanges connect data, and specifies needed quality of service based on the specified FLOWSPEC structures.

Syntax


SOCKET WSAJoinLeaf(
  _In_  SOCKET                s,
  _In_  const struct sockaddr *name,
  _In_  int                   namelen,
  _In_  LPWSABUF              lpCallerData,
  _Out_ LPWSABUF              lpCalleeData,
  _In_  LPQOS                 lpSQOS,
  _In_  LPQOS                 lpGQOS,
  _In_  DWORD                 dwFlags
);

Parameters

s [in]

Descriptor identifying a multipoint socket.

name [in]

Name of the peer to which the socket is to be joined.

namelen [in]

Length of name, in bytes.

lpCallerData [in]

Pointer to the user data that is to be transferred to the peer during multipoint session establishment.

lpCalleeData [out]

Pointer to the user data that is to be transferred back from the peer during multipoint session establishment.

lpSQOS [in]

Pointer to the FLOWSPEC structures for socket s, one for each direction.

lpGQOS [in]

Reserved for future use with socket groups. A pointer to the FLOWSPEC structures for the socket group (if applicable).

dwFlags [in]

Flags to indicate that the socket is acting as a sender (JL_SENDER_ONLY), receiver (JL_RECEIVER_ONLY), or both (JL_BOTH).

Return value

If no error occurs, WSAJoinLeaf returns a value of type SOCKET that is a descriptor for the newly created multipoint socket. Otherwise, a value of INVALID_SOCKET is returned, and 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 s when the join operation completes, either successfully or otherwise. The application must use either WSAAsyncSelect or WSAEventSelect with interest registered for the FD_CONNECT event in order to determine when the join operation has completed and checks the associated error code to determine the success or failure of the operation. The select function cannot be used to determine when the join operation completes.

Also, until the multipoint session join attempt completes all subsequent calls to WSAJoinLeaf on the same socket will fail with the error code WSAEALREADY. After the WSAJoinLeaf operation completes successfully, a subsequent attempt will usually fail with the error code WSAEISCONN. An exception to the WSAEISCONN rule occurs for a c_root socket that allows root-initiated joins. In such a case, another join may be initiated after a prior WSAJoinLeaf operation completes.

If the return error code indicates the multipoint session join attempt failed (that is, WSAECONNREFUSED, WSAENETUNREACH, WSAETIMEDOUT) the application can call WSAJoinLeaf again for the same socket.

Error codeMeaning
WSANOTINITIALISED

A successful WSAStartup call must occur before using this function.

WSAEADDRINUSE

The socket's local address is already in use and the socket was not marked to allow address reuse with SO_REUSEADDR. This error usually occurs at the time of bind, but could be delayed until this function if the bind was to a partially wildcard address (involving ADDR_ANY) and if a specific address needs to be committed at the time of this function.

WSAEADDRNOTAVAIL

The remote address is not a valid address (such as ADDR_ANY).

WSAEAFNOSUPPORT

Addresses in the specified family cannot be used with this socket.

WSAEALREADY

A nonblocking WSAJoinLeaf call is in progress on the specified socket.

WSAECONNREFUSED

The attempt to join was forcefully rejected.

WSAEFAULT

The name or the namelen parameter is not a valid part of the user address space, the namelen parameter is too small, the buffer length for lpCalleeData, lpSQOS, and lpGQOS are too small, or the buffer length for lpCallerData is too large.

WSAEINVAL

A WSAJoinLeaf function call was performed on a UDP socket that was opened without setting its WSA_FLAG_MULTIPOINT_C_LEAF or WSA_FLAG_MULTIPOINT_D_LEAF multipoint flag.

WSAEISCONN

The socket is already a member of the multipoint session.

WSAEINTR

A blocking Windows Socket 1.1 call was canceled through WSACancelBlockingCall.

WSAEINPROGRESS

A blocking Windows Sockets 1.1 call is in progress, or the service provider is still processing a callback function.

WSAENETDOWN

The network subsystem has failed.

WSAENETUNREACH

The network cannot be reached from this host at this time.

WSAENOBUFS

No buffer space is available. The socket cannot be joined.

WSAENOTSOCK

The descriptor is not a socket.

WSAEOPNOTSUPP

The FLOWSPEC structures specified in lpSQOS and lpGQOS cannot be satisfied.

WSAEPROTONOSUPPORT

The lpCallerData augment is not supported by the service provider.

WSAETIMEDOUT

The attempt to join timed out without establishing a multipoint session.

 

Remarks

The WSAJoinLeaf 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 WSAJoinLeaf function has the same parameters and semantics as WSAConnect except that it returns a socket descriptor (as in WSAAccept), and it has an additional dwFlags parameter. Only multipoint sockets created using WSASocket with appropriate multipoint flags set can be used for input parameter s in 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 WSAAsyncSelect or WSAEventSelect on the original socket s, except that closesocket may be invoked on this new socket descriptor to cancel a pending join operation. A root application in a multipoint session may call WSAJoinLeaf 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. Refer to Multipoint and Multicast Semantics for additional information.

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, since the function has effectively returned a successful start indication. When the final outcome success or failure becomes known, it may be reported through WSAAsyncSelect or WSAEventSelect depending 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 select function cannot be used to detect completion notification for WSAJoinLeaf.

The socket descriptor returned by WSAJoinLeaf 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. The newly created socket has the same properties as s, including asynchronous events registered with WSAAsyncSelect or with WSAEventSelect. It is not intended to be used for exchange of multipoint data, but rather is used to receive network event indications (for example, 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 closesocket to drop out of the multipoint session. Symmetrically, invoking closesocket on the c_leaf socket returned from WSAJoinLeaf will cause the socket in the corresponding leaf node to get an FD_CLOSE notification.

When WSAJoinLeaf 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 (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 or WSAAccept functions to admit the new leaf node. The value returned from either accept or WSAAccept is 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 lpCallerData is a value parameter that contains any user data that is to be sent along with the multipoint session join request. If lpCallerData is NULL, no user data will be passed to the peer. The lpCalleeData is a result parameter that will contain any user data passed back from the peer as part of the multipoint session establishment. The len member of the WSABUF structure pointed to by the lpCalleeData parameter initially contains the length of the buffer allocated by the application and pointed to by the buf member of the WSABUF structure. The len member of the WSABUF structure pointed to by the lpCalleeData parameter will be set to zero if no user data has been passed back. The lpCalleeData information will be valid when the multipoint join operation is complete.

For blocking sockets, this will be when the WSAJoinLeaf function 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 lpCalleeData is 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.

At multipoint session establishment time, an application can use the lpSQOS and/or lpGQOS parameters to override any previous quality of service specification made for the socket through WSAIoctl with the SIO_SET_QOS or SIO_SET_GROUP_QOS opcodes.

The lpSQOS parameter specifies the FLOWSPEC structures for socket s, one for each direction, followed by any additional provider-specific parameters. If either the associated transport provider in general or the specific type of socket in particular cannot honor the quality of service request, an error will be returned as indicated in the following. The respective sending or receiving flow specification values will be ignored for any unidirectional sockets. If no provider-specific parameters are specified, the buf and len members of the WSABUF structure pointed to by the lpCalleeData parameter should be set to NULL and zero, respectively. A NULL value for lpSQOS indicates no application-supplied quality of service.

Reserved for future socket groups. The lpGQOS parameter specifies the FLOWSPEC structures for the socket group (if applicable), one for each direction, followed by any additional provider-specific parameters. If no provider-specific parameters are specified, the the buf and len members of the WSABUF structure pointed to by the lpCalleeData parameter should be set to should be set to NULL and zero, respectively. A NULL value for lpGQOS indicates no application-supplied group quality of service. This parameter will be ignored if s is not the creator of the socket group.

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

Note  When issuing a blocking Winsock call such as WSAJoinLeaf, Winsock may need to wait for a network event before the call can complete. Winsock performs an alertable wait in this situation, which can be interrupted by an asynchronous procedure call (APC) scheduled on the same thread. Issuing another blocking Winsock call inside an APC that interrupted an ongoing blocking Winsock call on the same thread will lead to undefined behavior, and must never be attempted by Winsock clients.
 

Windows Phone 8: This function is supported for Windows Phone Store apps on Windows Phone 8 and later.

Windows 8.1 and Windows Server 2012 R2: This function is supported for Windows Store apps on Windows 8.1, Windows Server 2012 R2, and later.

Requirements

Minimum supported client

Windows 8.1, Windows Vista [desktop apps | Windows Store apps]

Minimum supported server

Windows Server 2003 [desktop apps | Windows Store apps]

Minimum supported phone

Windows Phone 8

Header

Winsock2.h

Library

Ws2_32.lib

DLL

Ws2_32.dll

See also

Winsock Reference
Winsock Functions
accept
bind
select
WSAAccept
WSAAsyncSelect
WSABUF
WSAEventSelect
WSASocket

 

 

Show: