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

Artículo
03/13/2024

La función LPWSPConnect establece una conexión a un par, intercambia datos de conexión y especifica la calidad de servicio necesaria en función de la especificación de flujo proporcionada.

Sintaxis

LPWSPCONNECT Lpwspconnect;

int Lpwspconnect(
  [in]  SOCKET s,
  [in]  const sockaddr *name,
  [in]  int namelen,
  [in]  LPWSABUF lpCallerData,
  [out] LPWSABUF lpCalleeData,
  [in]  LPQOS lpSQOS,
  [in]  LPQOS lpGQOS,
  [out] LPINT lpErrno
)
{...}

Parámetros

[in] s

Descriptor que identifica un socket no conectado.

[in] name

Nombre del elemento del mismo nivel al que se va a conectar el socket del 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 conexión.

[out] lpCalleeData

Puntero a un búfer en el que se pueden copiar los datos de usuario recibidos del mismo nivel durante el establecimiento de la conexión.

[in] lpSQOS

Puntero a las especificaciones de flujo para sockets, uno para cada dirección.

[in] lpGQOS

Reservado.

[out] lpErrno

Puntero al código de error.

Valor devuelto

Si no se produce ningún error, LPWSPConnect devuelve cero. De lo contrario, devuelve SOCKET_ERROR y hay disponible un código de error específico en lpErrno.

En un socket de bloqueo, el valor devuelto indica que el intento de conexión se ha realizado correctamente o no. Si el código de error devuelto indica que se produjo un error en el intento de conexión (es decir, WSAECONNREFUSED, WSAENETUNREACH, WSAETIMEDOUT), el cliente WINSock SPI puede llamar a LPWSPConnect 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 el enlace fuera 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.
WSAEINTR	(Bloqueo) la llamada se canceló a través de LPWSPCancelBlockingCall.
WSAEINPROGRESS	El bloqueo de la llamada a Winsock está en curso o el proveedor de servicios sigue procesando una función de devolución de llamada.
WSAEALREADY	La llamada a LPWSPConnect no desbloqueada está en curso en el socket especificado. Para conservar la compatibilidad con versiones anteriores, este error se notifica como WSAEINVAL a las aplicaciones de Windows Sockets 1.1 que se vinculan a Winsock.dll o a Wsock32.dll.
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	Se rechazó un intento de conexión.
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 para lpCalleeData, lpSQOS y lpGQOS es demasiado pequeña o la longitud del búfer de lpCallerData es demasiado grande.
WSAEINVAL	El parámetro s es un socket de escucha.
WSAEISCONN	El socket ya está conectado (solo sockets orientados a la conexión).
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 conectar.
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 conexión sin establecer una conexión.
WSAEWOULDBLOCK	El socket se marca como sin bloqueo y la conexión no se puede completar inmediatamente. Es posible seleccionar el socket mediante la función LPWSPSelect mientras se conecta mediante la función WSPSelect para seleccionarla para escribirla.
WSAEACCES	Error al intentar conectar el socket de datagrama a la dirección de difusión porque WSPSetSockOpt SO_BROADCAST no está habilitado.

Comentarios

Esta función se usa para crear una conexión al destino especificado y para realizar también una serie de otras operaciones auxiliares que se producen en el momento de la conexión. Si el socket, s, es independiente, el sistema asigna valores únicos a la asociación local y el socket se marca como enlazado.

En el caso de los sockets orientados a la conexión (por ejemplo, el tipo SOCK_STREAM), se inicia una conexión activa en el host especificado mediante el nombre (una dirección en el espacio de nombres del socket. Para obtener una descripción detallada, consulte LPWSPBind. Cuando esta llamada se completa correctamente, el socket está listo para enviar y recibir datos. Si el miembro de dirección de la estructura de nombres es ceros, LPWSPConnect devolverá el error WSAEADDRNOTAVAIL. Cualquier intento de volver a conectar una conexión activa producirá un error con el código de error WSAEISCONN.

En el caso de los sockets orientados a la conexión, los sockets sin bloqueo a menudo no es posible completar la conexión inmediatamente. En tal caso, esta función devuelve con el error WSAEWOULDBLOCK , pero la operación continúa. Cuando se conoce el resultado de éxito o error, se puede notificar de una de varias maneras en función de cómo se registre el cliente para la notificación. Si el cliente usa LPWSPSelect, se notifica si se ha realizado correctamente en el conjunto writefds y se notifica un error en el conjunto exceptfds . Si el cliente usa LPWSPAsyncSelect o LPWSPEventSelect, 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 de error.

Para un socket sin conexión (por ejemplo, tipo SOCK_DGRAM), la operación realizada por LPWSPConnect es establecer una dirección de destino predeterminada para que el socket se pueda usar con las operaciones de envío y recepción orientadas a la conexión posteriores (LPWSPSend, LPWSPRecv). Se descartarán todos los datagramas recibidos de una dirección distinta de la dirección de destino especificada. Si el miembro de dirección de la estructura de nombres es ceros, el socket se desconectará, la dirección remota predeterminada será indeterminada, por lo que las llamadas LPWSPSend y LPWSPRecv devolverán el código de error WSAENOTCONN. Sin embargo, LPWSPSendTo y LPWSPRecvFrom todavía se pueden usar. El destino predeterminado se puede cambiar simplemente llamando a LPWSPConnect de nuevo, incluso si el socket ya está conectado. Los datagramas en cola para la recepción se descartan si el nombre es diferente del LPWSPConnect anterior.

En el caso de los sockets sin conexión, el nombre puede indicar cualquier dirección válida, incluida una dirección de difusión. Sin embargo, para conectarse a una dirección de difusión, un socket debe tener WSPSetSockOpt habilitado SO_BROADCAST. De lo contrario, LPWSPConnect producirá un error con el código de error WSAEACCES.

En sockets sin conexión, no es posible el intercambio de datos de usuario a usuario y los parámetros correspondientes se omitirán de forma silenciosa.

El cliente SPI de Winsock es responsable de asignar cualquier espacio de memoria al que apunte directa o indirectamente cualquiera de los parámetros que especifica.

LpCallerData es un parámetro de valor que contiene los datos de usuario que se enviarán junto con la solicitud de conexión. Si lpCallerData es null, no se pasarán datos de usuario al mismo nivel. LpCalleeData es un parámetro de resultado que hará referencia a los datos de usuario pasados del mismo nivel como parte del establecimiento de la conexión. El lpCalleeData-len> contiene inicialmente la longitud del búfer asignado por el cliente SPI de Winsock y apuntado a por 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 conexión. Para los sockets de bloqueo, esto será cuando la función LPWSPConnect devuelva. En el caso de los sockets sin bloqueo, esto será después de que se haya producido la notificación de FD_CONNECT. 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 a las aplicaciones implicadas.

En el momento de la conexión, un cliente SPI de Winsock puede usar el parámetro lpSQOS para invalidar cualquier especificación QoS anterior realizada para el socket a través de LPWSPIoctl con el SIO_SET_QOS código de operación.

El 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 ninguna aplicación proporcionó calidad de servicio.

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 Winsock debe descartar y volver a crear los sockets necesarios para volver a un punto estable.

Requisitos

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