WSPJoinLeaf
A version of this page is also available for
4/8/2010
This function joins a leaf node into a multipoint session, and exchanges connect data.
Note
WSPJoinLeaf is not supported for the default TCP/UDP provider in Windows Embedded CE. However, third parties can implement their own provider and have support for this function if they choose.
Syntax
SOCKET WSPJoinLeaf(
SOCKET s,
const struct sockaddr FAR* name,
int namelen,
LPWSABUF lpCallerData,
LPWSABUF lpCalleeData,
LPQOS lpSQOS,
LPQOS lpGQOS,
DWORD dwFlags,
LPINT lpErrno
);
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 the name.
- 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] Reserved.
- lpGQOS
[in] Reserved.
- dwFlags
[in] Flags to indicate that the socket is acting as a sender, receiver, or both.
- lpErrno
[out] Pointer to the error code.
Return Value
This function always returns SOCKET_ERROR and sets lpErrno to WSASYSCALLFAILURE on Windows Embedded CE.
Remarks
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 WSPConnect except that it returns a socket descriptor (as in WSPAccept), and it has an additional dwFlags parameter. Only multipoint sockets created using WSPSocket with appropriate multipoint flags set can be used for input parameter s in this function. If the socket is in the nonblocking mode, the returned socket descriptor will not be useable until after a corresponding FD_CONNECT indication on the original socket s has been received, except that closesocket can be invoked on this new socket descriptor to cancel a pending join operation. A root node in a multipoint session can call WSPJoinLeaf one 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 WSPEventSelect 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 Windows Sockets SPI client 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. lpCalleeData->len initially contains the length of the buffer allocated by the Windows Sockets SPI client and pointed to by lpCalleeData->buf. lpCalleeData->len 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 WSPJoinLeaf function returns. For nonblocking sockets, this will be after the FD_CONNECT notification has occurred 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 and/or the applications involved.
The dwFlags 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).
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.
Requirements
| Header | ws2spi.h |
| Library | Ws2.lib |
| Windows Embedded CE | Windows CE .NET 4.0 and later |
| Windows Mobile | Windows Mobile Version 5.0 and later |