Función de devolución de llamada LPWSPJOINLEAF (ws2spi.h)

Artículo
08/28/2023

La función WSPJoinLeaf 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 especificaciones de flujo proporcionadas.

Sintaxis

LPWSPJOINLEAF Lpwspjoinleaf;

SOCKET Lpwspjoinleaf(
  [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,
  [out] LPINT lpErrno
)
{...}

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 de la estructura sockaddr .

[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 especificaciones de flujo para sockets, uno para cada dirección.

[in] lpGQOS

Reservado.

[in] dwFlags

Marcas para indicar que el socket actúa como remitente, receptor o ambos.

[out] lpErrno

Puntero al código de error.

Valor devuelto

Si no se produce ningún error, WSPJoinLeaf 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 hay disponible un código de error específico en lpErrno.

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 un valor devuelto de un descriptor de socket válido. Posteriormente, se proporciona una indicación de FD_CONNECT cuando se completa la operación de combinación, ya sea correctamente o de otro modo. El código de error asociado al FD_CONNECT indica el éxito o error del WSPJoinLeaf.

Además, hasta que el intento de combinación de sesión de varios puntos complete todas las llamadas posteriores a WSPJoinLeaf en el mismo socket, se producirá un error con el código de error WSAEALREADY. Una vez que WSPJoinLeaf se complete correctamente, 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 un WSPJoinLeaf 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), el cliente SPI de Windows Sockets puede llamar a WSPJoinLeaf de nuevo para el mismo socket.

Código de error	Significado
WSAENETDOWN	Error en el subsistema de red.
WSAEADDRINUSE	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 que esta función si bind fuera a una dirección de caracteres comodín parcial (que implique ADDR_ANY) y si una dirección específica debe "confirmarse" en el momento de esta función.
WSAEINTR	(Bloqueo) la llamada se canceló a través de WSPCancelBlockingCall.
WSAEINPROGRESS	El bloqueo de la llamada a Windows Sockets está en curso o el proveedor de servicios sigue procesando una función de devolución de llamada.
WSAEALREADY	La llamada WSPJoinLeaf no desbloqueada está en curso en el socket especificado.
WSAEADDRNOTAVAIL	La dirección remota no es una dirección válida (por ejemplo, ADDR_ANY).
WSAEAFNOSUPPORT	Las direcciones de la familia especificada no se pueden usar con este socket.
WSAECONNREFUSED	El intento de unirse se rechazó forzosamente.
WSAEFAULT	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.
WSAEISCONN	Socket ya es miembro de la sesión de varios puntos.
WSAENETUNREACH	La red no se puede alcanzar desde este host en estos momentos.
WSAENOBUFS	No hay espacio disponible en el búfer. El socket no se puede unir.
WSAENOTSOCK	El descriptor no es un socket.
WSAEOPNOTSUPP	No se pueden cumplir las especificaciones de flujo especificadas en lpSQOS .
WSAEPROTONOSUPPORT	El aumento lpCallerData no es compatible con el proveedor de servicios.
WSAETIMEDOUT	Se agota el tiempo de espera de la unión sin establecer una sesión de varios puntos.

Observaciones

Esta función se usa para unir un nodo hoja a una sesión de varios puntos y para realizar también una serie de otras operaciones auxiliares que se producen en tiempo de unión de sesión. Si el socket, s, es unbound, los valores únicos se asignan a la asociación local por parte del sistema y el socket se marca como enlazado.

WSPJoinLeaf tiene los mismos parámetros y semántica que LPWSPConnect , salvo que devuelve un descriptor de socket (como en LPWSPAccept) y tiene un parámetro dwFlags adicional. Solo se pueden usar sockets multipunto creados con LPWSPSocket con marcas de varios puntos adecuadas establecidas para los parámetros de entrada de esta función. Si el socket está en modo de no bloqueo, el descriptor de socket devuelto no se podrá usar hasta después de que se haya recibido una indicación de FD_CONNECT correspondiente en el socket original, salvo que se pueda invocar closesocket en este nuevo descriptor de socket para cancelar una operación de combinación pendiente. Un nodo raíz de una sesión de varios puntos puede llamar a WSPJoinLeaf 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 Multidifusión independiente del protocolo y Multipoint en el SPI 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. En este caso, no hay ningún código de error como WSAEWOULDBLOCK , ya que la función ha devuelto efectivamente una indicación de "inicio correcto". Cuando se conozca el resultado final correcto o erróneo, se puede notificar a través de LPWSPAsyncSelect o LPWSPEventSelect 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. Tenga en cuenta que LPWSPSelect no se puede usar para detectar la notificación de finalización de WSPJoinLeaf.

El descriptor de socket devuelto por WSPJoinLeaf 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. (Como se describe en la sección Asignación de descriptores, cuando se asignan nuevos descriptores de socket a proveedores IFS debe llamar a WPUModifyIFSHandle y los proveedores que no son IFS deben llamar a WPUCreateSocketHandle). El socket recién creado tiene las mismas propiedades que los eventos asincrónicos registrados con LPWSPAsyncSelect o con LPWSPEventSelect. 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 LPWSPCloseSocket para abandonar la sesión de varios puntos. Simétricamente, invocar WSPCloseSocket en el socket c_leaf devuelto desde WSPJoinLeaf hará que el socket en el nodo hoja correspondiente obtenga FD_CLOSE notificación.

Cuando se invoca WSPJoinLeaf con un socket c_leaf, el parámetro name contiene la dirección del nodo raíz (para un esquema de control raíz) o una sesión de varios puntos existente (esquema de control no raíz) 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 el modo de escucha mediante una llamada a LPWSPListen. 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 LPWSPAccept habituales para admitir el nuevo nodo hoja. El valor devuelto por WSPAccept también es un descriptor de socket c_leaf igual que los devueltos desde WSPJoinLeaf. Para dar cabida a esquemas de varios puntos que permiten combinaciones iniciadas por raíz y de hoja, es aceptable que un socket c_root que ya esté en modo de escucha se use como entrada para WSPJoinLeaf.

El cliente SPI de Windows Sockets 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 pasados del mismo nivel como parte del establecimiento de la sesión multipunto. lpCalleeData-len> contiene inicialmente la longitud del búfer asignado por el cliente SPI de Windows Sockets y apuntado a lpCalleeData-buf.> lpCalleeData-len> se establecerá en cero si no se han devuelto datos de usuario. La información lpCalleeData será válida cuando se complete la operación de combinación multipunto. Para los sockets de bloqueo, esto será cuando se devuelva la función WSPJoinLeaf . En el caso de los sockets sin bloqueo, esto será después de que se haya producido la notificación de FD_CONNECT en los sockets originales. Si lpCalleeData es NULL, no se devolverán datos de usuario. El formato exacto de los datos de usuario es específico de la familia de direcciones a la que pertenece el socket o las aplicaciones implicadas.

En el momento de establecimiento de la sesión multipunto, un cliente SPI de Windows Sockets puede usar los parámetros lpSQOS para invalidar cualquier especificación QoS anterior realizada para el socket a través de LPWSPIoctl con el código de operación de SIO_SET_QOS.

lpSQOS especifica las especificaciones de flujo 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 solicitud QoS, se devolverá un error como se indica a continuación. Los valores de especificación de flujo de envío o recepción se omitirán, respectivamente, para los sockets unidireccionales. Si no se proporcionan parámetros específicos del proveedor, los miembros buf y len de lpSQOS-ProviderSpecific> 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.

El parámetro dwFlags se usa para indicar si el socket actuará solo como remitente (JL_SENDER_ONLY), solo como receptor (JL_RECEIVER_ONLY) o ambos (JL_BOTH).

**Nota** Cuando los sockets conectados se interrumpen (es decir, se cierran por cualquier motivo), se deben descartar y volver a crear. Es más seguro suponer que, cuando las cosas se awry por cualquier motivo en un socket conectado, el cliente SPI de Windows Sockets debe descartar y volver a crear los sockets necesarios para volver a un punto estable.

Requisitos


Cliente mínimo compatible	Windows 2000 Professional [solo aplicaciones de escritorio]
Servidor mínimo compatible	Windows 2000 Server [solo aplicaciones de escritorio]
Plataforma de destino	Windows
Encabezado	ws2spi.h