The Windows Sockets connect
function joins a leaf node into a multipoint session, exchanges connect data,
and specifies needed quality of service based on the supplied flow
SOCKET WSAJoinLeaf (
| SOCKET s,
| const struct sockaddr FAR * name,
| int namelen,
| LPWSABUF lpCallerData,
| LPWSABUF lpCalleeData,
| LPQOS lpSQOS,
| LPQOS lpGQOS,
| DWORD dwFlags
[in] A descriptor identifying a multipoint socket.
[in] The name of the peer to which the socket is to be joined.
[in] The length of the name
[in] A pointer to the user data that is to be transferred to the peer during
multipoint session establishment.
[out] A pointer to the user data that is to be transferred back from the peer
during multipoint session establishment.
[in] A pointer to the flow specifications for socket s
, one for each direction.
[in] A pointer to the flow specifications for the socket group (if applicable).
[in] Flags to indicate that the socket is acting as a sender, receiver, or
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.
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 may be used for input parameter s
in this function. If the socket is in the nonblocking mode, the returned
socket descriptor will not be usable until after a corresponding FD_CONNECT
indication has been received. 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.
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
, but not
including the c_root socket's group ID, if any. 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 may 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
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 FD_CLOSE
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 the 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
functions to admit the new leaf node. The value returned from either accept
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.
is a value parameter which 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 which will contain any user data passed back from the
peer as part of the multipoint session establishment. lpCalleeData->len
initially contains the length of the buffer allocated by the application and
pointed to by lpCalleeData->buf
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 WSAConnect
function returns. For nonblocking sockets, this will be after the FD_CONNECT
notification has occurred. 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 may use the lpSQOS
parameters to override any previous QOS specification made for the socket
with either the SIO_SET_QOS or SIO_SET_GROUP_QOS opcodes.
specifies the flow specifications 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 QOS request, an error will be
returned as indicated below. The sending or receiving flow specification values will
be ignored, respectively, for any unidirectional sockets. If no
provider-specific parameters are supplied, the buf
fields of lpSQOS->ProviderSpecific
should be set to NULL and zero, respectively. A NULL value for lpSQOS
indicates no application supplied QOS.
specifies the flow specifications for the socket group (if applicable), one
for each direction, followed by any additional provider-specific parameters. If
no provider-specific parameters are supplied, the buf
fields of lpSQOS->ProviderSpecific
should be set to NULL and zero, respectively. A NULL value for lpGQOS
indicates no application-supplied group QOS. This parameter will be ignored
is not the creator of the socket group.
parameter 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).
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.
If no error occurs, WSAJoinLeaf
returns a value of type SOCKET which is a descriptor for the newly created
multipoint socket. Otherwise, a value of INVALID_SOCKET is returned, and a
specific error code may be retrieved by calling WSAGetLastError.
On a blocking socket, the return value indicates success or failure of the
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 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. Note that 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.
If the return error code indicates the multipoint session join attempt failed
(that is, WSAECONNREFUSED, WSAENETUNREACH, WSAETIMEDOUT) the application may
call WSAJoinLeaf again for the same socket.
||A successful WSAStartup must occur before using this function.
||The network subsystem has failed.
||The specified address is already in use.
||The (blocking) call was canceled through WSACancelBlockingCall.
||A blocking Windows Sockets 1.1 call is in progress, or the service provider is
still processing a callback function.
||A nonblocking WSAJoinLeaf call is in progress on the specified socket.
||The specified address is not available from the local machine.
||Addresses in the specified family cannot be used with this socket.
||The attempt to join was forcefully rejected.
||The name or the namelen argument is not a valid part of the user address space, the namelen argument is too small, the buffer length for lpCalleeData, lpSQOS, and lpGQOS are too small, or the buffer length for lpCallerData is too large.
||The socket is already member of the multipoint session.
||The network cannot be reached from this host at this time.
||No buffer space is available. The socket cannot be joined.
||The descriptor is not a socket.
||The flow specifications specified in lpSQOS and lpGQOS cannot be satisfied.
||The lpCallerData augment is not supported by the service provider.
||Attempt to join timed out without establishing a multipoint session.
||The socket is marked as nonblocking and the multipoint session join operation
cannot be completed immediately. It is possible to select the socket while it is connecting by selecting it for writing.
- Software for developers
Software for Android Developers
- More information resources
Unix Manual Pages