Función WSAJoinLeaf (winsock2.h)
La función WSAJoinLeaf combina un nodo hoja en una sesión de varios puntos, intercambia datos de conexión y especifica la calidad de servicio necesaria en función de las estructuras FLOWSPEC especificadas.
Sintaxis
SOCKET WSAAPI WSAJoinLeaf(
[in] SOCKET s,
[in] const sockaddr *name,
[in] int namelen,
[in] LPWSABUF lpCallerData,
[out] LPWSABUF lpCalleeData,
[in] LPQOS lpSQOS,
[in] LPQOS lpGQOS,
[in] DWORD dwFlags
);
Parámetros
[in] s
Descriptor que identifica un socket multipunto.
[in] name
Nombre del elemento del mismo nivel al que se va a unir el socket.
[in] namelen
Longitud del nombre, en bytes.
[in] lpCallerData
Puntero a los datos de usuario que se van a transferir al mismo nivel durante el establecimiento de la sesión multipunto.
[out] lpCalleeData
Puntero a los datos de usuario que se van a transferir del mismo nivel durante el establecimiento de la sesión multipunto.
[in] lpSQOS
Puntero a las estructuras FLOWSPEC para sockets, uno para cada dirección.
[in] lpGQOS
Reservado para uso futuro con grupos de sockets. Puntero a las estructuras FLOWSPEC del grupo de sockets (si procede).
[in] dwFlags
Marcas para indicar que el socket actúa como remitente (JL_SENDER_ONLY), receptor (JL_RECEIVER_ONLY) o ambos (JL_BOTH).
Valor devuelto
Si no se produce ningún error, WSAJoinLeaf devuelve un valor de tipo SOCKET que es un descriptor para el socket multipunto recién creado. De lo contrario, se devuelve un valor de INVALID_SOCKET y se puede recuperar un código de error específico mediante una llamada a WSAGetLastError.
En un socket de bloqueo, el valor devuelto indica que la operación de combinación se ha realizado correctamente o no.
Con un socket sin bloqueo, el inicio correcto de una operación de combinación se indica mediante una devolución de un descriptor de socket válido. Posteriormente, se proporcionará una indicación de FD_CONNECT en el socket original cuando se complete la operación de combinación, ya sea correctamente o de otro modo. La aplicación debe usar WSAAsyncSelect o WSAEventSelect con interés registrado para el evento FD_CONNECT con el fin de determinar cuándo se ha completado la operación de combinación y comprueba el código de error asociado para determinar el éxito o error de la operación. La función select no se puede usar para determinar cuándo se completa la operación de combinación.
Además, hasta que el intento de combinación de sesión de varios puntos complete todas las llamadas posteriores a WSAJoinLeaf en el mismo socket, se producirá un error con el código de error WSAEALREADY. Una vez completada correctamente la operación WSAJoinLeaf , normalmente se producirá un error en un intento posterior con el código de error WSAEISCONN. Se produce una excepción a la regla WSAEISCONN para un socket c_root que permite combinaciones iniciadas por la raíz. En tal caso, se puede iniciar otra combinación después de que se complete una operación WSAJoinLeaf anterior.
Si el código de error devuelto indica que se produjo un error en el intento de combinación de sesión multipunto (es decir, WSAECONNREFUSED, WSAENETUNREACH, WSAETIMEDOUT), la aplicación puede llamar a WSAJoinLeaf de nuevo para el mismo socket.
| Código de error | Significado |
|---|---|
| Debe producirse una llamada WSAStartup correcta antes de usar esta función. | |
| La dirección local del socket ya está en uso y el socket no se marcó para permitir la reutilización de direcciones con SO_REUSEADDR. Este error suele producirse en el momento del enlace, pero podría retrasarse hasta esta función si el enlace era a una dirección con caracteres comodín parcial (que implica ADDR_ANY) y si es necesario confirmar una dirección específica en el momento de esta función. | |
| La dirección remota no es una dirección válida (como ADDR_ANY). | |
| Las direcciones de la familia especificada no se pueden usar con este socket. | |
| Una llamada WSAJoinLeaf sin bloqueo está en curso en el socket especificado. | |
| El intento de unirse se rechazó forzosamente. | |
| El nombre o el parámetro namelen no es una parte válida del espacio de direcciones del usuario, el parámetro namelen es demasiado pequeño, la longitud del búfer de lpCalleeData, lpSQOS y lpGQOS son demasiado pequeñas o la longitud del búfer de lpCallerData es demasiado grande. | |
| Se realizó una llamada de función WSAJoinLeaf en un socket UDP que se abrió sin establecer su marca WSA_FLAG_MULTIPOINT_C_LEAF o WSA_FLAG_MULTIPOINT_D_LEAF multipunto. | |
| El socket ya es miembro de la sesión de varios puntos. | |
| Se canceló una llamada de Bloqueo de Windows Socket 1.1 a través de WSACancelBlockingCall. | |
| Una llamada de Bloqueo de Windows Sockets 1.1 está en curso o el proveedor de servicios sigue procesando una función de devolución de llamada. | |
| Error en el subsistema de red. | |
| La red no se puede alcanzar desde este host en estos momentos. | |
| No hay espacio disponible en el búfer. El socket no se puede unir. | |
| El descriptor no es un socket. | |
| No se pueden satisfacer las estructuras FLOWSPEC especificadas en lpSQOS y lpGQOS . | |
| El aumento lpCallerData no es compatible con el proveedor de servicios. | |
| El intento de unirse agota el tiempo de espera sin establecer una sesión de varios puntos. |
Comentarios
La función WSAJoinLeaf se usa para unir un nodo hoja a una sesión de varios puntos y para realizar una serie de otras operaciones auxiliares que también se producen en tiempo de unión de sesión. Si el socket s es independiente, el sistema asigna valores únicos a la asociación local y el socket se marca como enlazado.
La función WSAJoinLeaf tiene los mismos parámetros y semántica que WSAConnect , salvo que devuelve un descriptor de socket (como en WSAAccept) y tiene un parámetro dwFlags adicional. Solo se pueden usar sockets multipunto creados con WSASocket con marcas multipunto adecuadas establecidas para los parámetros de entrada de esta función. El descriptor de socket devuelto no se podrá usar hasta que se complete la operación de combinación. Por ejemplo, si el socket está en modo de no bloqueo después de que se haya recibido una indicación de FD_CONNECT correspondiente de WSAAsyncSelect o WSAEventSelect en los sockets originales, salvo que se puede invocar closesocket en este nuevo descriptor de socket para cancelar una operación de combinación pendiente. Una aplicación raíz en una sesión de varios puntos puede llamar a WSAJoinLeaf una o varias veces para agregar un número de nodos hoja, pero como máximo una solicitud de conexión multipunto puede estar pendiente a la vez. Consulte La semántica multipunto y multidifusión para obtener información adicional.
En el caso de sockets sin bloqueo, a menudo no es posible completar la conexión inmediatamente. En tal caso, esta función devuelve un descriptor de socket inutilizable y la operación continúa. No hay ningún código de error como WSAEWOULDBLOCK en este caso, ya que la función ha devuelto efectivamente una indicación de inicio correcta. Cuando se conoce el resultado final correcto o erróneo, se puede notificar a través de WSAAsyncSelect o WSAEventSelect en función de cómo se registre el cliente para la notificación en los sockets originales. En cualquier caso, la notificación se anuncia con FD_CONNECT y el código de error asociado al FD_CONNECT indica que se ha realizado correctamente o un motivo específico del error. La función select no se puede usar para detectar la notificación de finalización de WSAJoinLeaf.
El descriptor de socket devuelto por WSAJoinLeaf es diferente en función de si el descriptor de socket de entrada, s, es un c_root o un c_leaf. Cuando se usa con un socket de c_root, el parámetro name designa un nodo hoja determinado que se va a agregar y el descriptor de socket devuelto es un socket c_leaf correspondiente al nodo hoja recién agregado. El socket recién creado tiene las mismas propiedades que s, incluidos los eventos asincrónicos registrados con WSAAsyncSelect o con WSAEventSelect. No está diseñado para usarse para el intercambio de datos de varios puntos, sino que se usa para recibir indicaciones de eventos de red (por ejemplo, FD_CLOSE) para la conexión que existe con el c_leaf concreto. Algunas implementaciones de varios puntos también pueden permitir que este socket se use para chats laterales entre la raíz y un nodo hoja individual. Se recibirá una indicación de FD_CLOSE para este socket si el nodo hoja correspondiente llama a closesocket para abandonar la sesión de varios puntos. Simétricamente, invocar closesocket en el socket c_leaf devuelto desde WSAJoinLeaf hará que el socket en el nodo hoja correspondiente obtenga una notificación de FD_CLOSE.
Cuando se invoca WSAJoinLeaf con un socket de c_leaf, el parámetro name contiene la dirección de la aplicación raíz (para un esquema de control raíz) o una sesión de varios puntos (esquema de control no raíz) existente y el descriptor de socket devuelto es el mismo que el descriptor de socket de entrada. En otras palabras, no se asigna un nuevo descriptor de socket. En un esquema de control raíz, la aplicación raíz colocaría su socket c_root en modo de escucha mediante una llamada a listen. La notificación estándar FD_ACCEPT se entregará cuando el nodo hoja solicite unirse a sí mismo a la sesión de varios puntos. La aplicación raíz usa las funciones de aceptación habituales o WSAAccept para admitir el nuevo nodo hoja. El valor devuelto por accept o WSAAccept también es un descriptor de socket c_leaf igual que los devueltos desde WSAJoinLeaf. Para dar cabida a esquemas de varios puntos que permiten combinaciones iniciadas por raíz y iniciadas por hoja, es aceptable que un socket de c_root que ya esté en modo de escucha se use como entrada para WSAJoinLeaf.
La aplicación es responsable de asignar cualquier espacio de memoria al que apunte directa o indirectamente cualquiera de los parámetros que especifique.
LpCallerData es un parámetro de valor que contiene los datos de usuario que se van a enviar junto con la solicitud de combinación de sesión multipunto. Si lpCallerData es NULL, no se pasarán datos de usuario al mismo nivel. LpCalleeData es un parámetro de resultado que contendrá los datos de usuario que se devuelven desde el mismo nivel como parte del establecimiento de la sesión de varios puntos. El miembro len de la estructura WSABUF a la que apunta el parámetro lpCalleeData inicialmente contiene la longitud del búfer asignado por la aplicación y apuntado por el miembro buf de la estructura WSABUF . El miembro len de la estructura WSABUF a la que apunta el parámetro lpCalleeData se establecerá en cero si no se ha pasado ningún dato de usuario. La información de lpCalleeData será válida cuando se complete la operación de combinación de varios puntos.
Para los sockets de bloqueo, será cuando la función WSAJoinLeaf devuelva. En el caso de los sockets sin bloqueo, esto será después de que se haya completado la operación de combinación. Por ejemplo, esto podría ocurrir después de FD_CONNECT notificación en el socket original s). Si lpCalleeData es NULL, no se devolverá ningún dato de usuario. El formato exacto de los datos de usuario es específico de la familia de direcciones a la que pertenece el socket.
En el momento del establecimiento de sesiones de varios puntos, una aplicación puede usar los parámetros lpSQOS o lpGQOS para invalidar cualquier calidad de servicio anterior realizada para el socket a través de WSAIoctl con los códigos de operación SIO_SET_QOS o SIO_SET_GROUP_QOS.
El parámetro lpSQOS especifica las estructuras FLOWSPEC para sockets, una para cada dirección, seguida de cualquier parámetro adicional específico del proveedor. Si el proveedor de transporte asociado en general o el tipo específico de socket en particular no puede respetar la calidad de la solicitud de servicio, se devolverá un error como se indica a continuación. Los valores de especificación de flujo de envío o recepción respectivos se omitirán para los sockets unidireccionales. Si no se especifica ningún parámetro específico del proveedor, los miembros buf y len de la estructura WSABUF a la que apunta el parámetro lpCalleeData deben establecerse en NULL y cero, respectivamente. Un valor NULL para lpSQOS indica que no hay ninguna calidad de servicio proporcionada por la aplicación.
Reservado para futuros grupos de sockets. El parámetro lpGQOS especifica las estructuras FLOWSPEC para el grupo de sockets (si procede), una para cada dirección, seguida de cualquier parámetro adicional específico del proveedor. Si no se especifica ningún parámetro específico del proveedor, los miembros buf y len de la estructura WSABUF a la que apunta el parámetro lpCalleeData deben establecerse en null y cero , respectivamente. Un valor NULL para lpGQOS indica que no hay calidad de servicio proporcionada por la aplicación. Este parámetro se omitirá si s no es el creador del grupo de sockets.
Cuando se interrumpen los sockets conectados (es decir, se cierran por cualquier motivo), se deben descartar y volver a crear. Es más seguro suponer que, cuando las cosas van awry por cualquier motivo en un socket conectado, la aplicación debe descartar y volver a crear los sockets necesarios para volver a un punto estable.
Windows 8.1 y Windows Server 2012 R2: esta función es compatible con las aplicaciones de la Tienda Windows en Windows 8.1, Windows Server 2012 R2 y versiones posteriores.
Requisitos
| Requisito | Value |
|---|---|
| Cliente mínimo compatible | Windows 8.1, Windows Vista [aplicaciones de escritorio | Aplicaciones para UWP] |
| Servidor mínimo compatible | Windows Server 2003 [aplicaciones de escritorio | aplicaciones para UWP] |
| Plataforma de destino | Windows |
| Encabezado | winsock2.h |
| Library | Ws2_32.lib |
| Archivo DLL | Ws2_32.dll |