Función WSAConnect (winsock2.h)

Artículo
08/27/2023

La función WSAConnect establece una conexión a otra aplicación de socket, intercambia datos de conexión y especifica la calidad de servicio necesaria en función de la estructura FLOWSPEC especificada.

Sintaxis

int WSAAPI WSAConnect(
  [in]  SOCKET         s,
  [in]  const sockaddr *name,
  [in]  int            namelen,
  [in]  LPWSABUF       lpCallerData,
  [out] LPWSABUF       lpCalleeData,
  [in]  LPQOS          lpSQOS,
  [in]  LPQOS          lpGQOS
);

Parámetros

[in] s

Descriptor que identifica un socket no conectado.

[in] name

Puntero a una estructura de sockaddr que especifica la dirección a la que se va a conectar. Para IPv4, el sockaddr contiene AF_INET para la familia de direcciones, la dirección IPv4 de destino y el puerto de destino. Para IPv6, la estructura sockaddr contiene AF_INET6 para la familia de direcciones, la dirección IPv6 de destino, el puerto de destino y puede contener información adicional sobre el flujo y el identificador de ámbito.

[in] namelen

Longitud, en bytes, de la estructura sockaddr a la que apunta el parámetro name .

[in] lpCallerData

Puntero a los datos de usuario que se van a transferir al otro socket durante el establecimiento de la conexión. Vea la sección Comentarios.

[out] lpCalleeData

Puntero a los datos de usuario que se van a transferir desde el otro socket durante el establecimiento de la conexión. Vea la sección Comentarios.

[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 para el grupo de sockets (si procede). Este parámetro debe ser NULL.

Valor devuelto

Si no se produce ningún error, WSAConnect devuelve cero. De lo contrario, devuelve SOCKET_ERROR y se puede recuperar un código de error específico llamando a WSAGetLastError. En un socket de bloqueo, el valor devuelto indica que el intento de conexión se ha realizado correctamente o no.

Con un socket de no bloqueo, el intento de conexión no se puede completar inmediatamente. En este caso, WSAConnect devolverá SOCKET_ERROR y WSAGetLastError devolverá WSAEWOULDBLOCK; por lo tanto, la aplicación podría:

Use select para determinar la finalización de la solicitud de conexión comprobando si el socket se puede escribir.
Si la aplicación usa WSAAsyncSelect para indicar interés en los eventos de conexión, la aplicación recibirá una notificación de FD_CONNECT cuando se complete la operación de conexión (correcta o no).
Si la aplicación usa WSAEventSelect para indicar interés en los eventos de conexión, el objeto de evento asociado se indicará cuando se complete la operación de conexión (correcta o no).

Para un socket de no bloqueo, hasta que el intento de conexión complete todas las llamadas posteriores a WSAConnect en el mismo socket producirá un error con el código de error WSAEALREADY.

Si el código de error devuelto indica que se produjo un error en el intento de conexión (es decir, WSAECONNREFUSED, WSAENETUNREACH, WSAETIMEDOUT), la aplicación puede llamar a WSAConnect de nuevo para el mismo socket.

Código de error	Significado
WSANOTINITIALISED	Debe producirse una llamada de WSAStartup correcta antes de usar esta función.
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 durante la ejecución del enlace, pero podría retrasarse hasta que esta función si la función de enlace funciona en 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	La llamada a Windows Socket 1.1 (bloqueo) se canceló a través de WSACancelBlockingCall.
WSAEINPROGRESS	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.
WSAEALREADY	Una llamada de conexión sin bloqueo o WSAConnect está en curso en el socket especificado.
WSAEADDRNOTAVAIL	La dirección remota no es una dirección válida (como ADDR_ANY).
WSAEAFNOSUPPORT	Las direcciones de la familia especificada no se pueden usar con este socket.
WSAECONNREFUSED	El intento de conexión se rechazó.
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 son demasiado pequeñas o la longitud del búfer para lpCallerData es demasiado grande.
WSAEINVAL	El parámetro s es un socket de escucha o la dirección de destino especificada no es coherente con la del grupo restringido al que pertenece el socket o el parámetro lpGQOS no es NULL.
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.
WSAEHOSTUNREACH	Se intentó realizar una operación de socket a un host inalcanzable.
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 satisfacer las estructuras FLOWSPEC especificadas en lpSQOS y lpGQOS .
WSAEPROTONOSUPPORT	El proveedor de servicios no admite el parámetro lpCallerData .
WSAETIMEDOUT	Se ha agotado el tiempo de espera de la conexión sin poder establecer una conexión.
WSAEWOULDBLOCK	El socket está marcado como de no bloqueo y la conexión no puede completarse inmediatamente.
WSAEACCES	Error al intentar conectar el socket de datagrama a la dirección de difusión porque setockopt SO_BROADCAST no está habilitado.

Comentarios

La función WSAConnect se usa para crear una conexión al destino especificado y para realizar una serie de otras operaciones auxiliares que se producen en el momento de la conexió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.

Para las aplicaciones destinadas a Windows Vista y versiones posteriores, considere la posibilidad de usar la función WSAConnectByList o WSAConnectByName , lo que simplifica considerablemente el diseño de aplicaciones cliente.

En el caso de los sockets orientados a la conexión (por ejemplo, escriba SOCK_STREAM), se inicia una conexión activa en el host externo con el nombre (una dirección en el espacio de nombres del socket; para obtener una descripción detallada, consulte bind). Cuando esta llamada se completa correctamente, el socket está listo para enviar o recibir datos. Si el parámetro address de la estructura de nombres es de ceros, WSAConnect devolverá el error WSAEADDRNOTAVAIL. Cualquier intento de volver a conectar una conexión activa producirá un error con el código de error WSAEISCONN.

Nota Si se abre un socket, se realiza una llamada a setsockopt y, a continuación, se realiza una llamada sendto , Windows Sockets realiza una llamada de función de enlace implícita.

En el caso de los sockets orientados a la conexión y sin bloqueo, a menudo no es posible completar la conexión inmediatamente. En tales casos, esta función devuelve el error WSAEWOULDBLOCK. Sin embargo, la operación continúa. Cuando se conoce el resultado correcto o de 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 select, se notifica el éxito en el conjunto writefds y se notifica un error en el conjunto exceptfds . Si el cliente usa WSAAsyncSelect o WSAEventSelect, 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, escriba SOCK_DGRAM), la operación realizada por WSAConnect es simplemente para establecer una dirección de destino predeterminada para que el socket se pueda usar en las operaciones de envío y recepción orientadas a la conexión posteriores (envío, WSASend, recv y WSARecv). Se descartarán los datagramas recibidos de una dirección distinta de la dirección de destino especificada. Si toda la estructura de nombres es ceros (no solo el parámetro address de la estructura de nombres), el socket se desconectará. A continuación, la dirección remota predeterminada será indeterminada, por lo que las llamadas de WSASend, recv y WSARecv devolverán el código de error WSAENOTCONN. Sin embargo, todavía se puede usar sendto, WSASendTo, recvfrom y WSARecvFrom . El destino predeterminado se puede cambiar simplemente llamando a WSAConnect de nuevo, incluso si el socket ya está conectado. Los datagramas en cola para recibir se descartan si el nombre es diferente del WSAConnect 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 setockopt SO_BROADCAST habilitado. De lo contrario, WSAConnect producirá un error con el código de error WSAEACCES.

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

La aplicación es responsable de asignar cualquier espacio de memoria al que apunte directa o indirectamente cualquiera de los parámetros que especifique.

El parámetro lpCallerData contiene un puntero a los datos de usuario que se van a enviar junto con la solicitud de conexión (denominada datos de conexión). Se trata de datos adicionales, no en el flujo de datos de red normal, que se envía con solicitudes de red para establecer una conexión. Esta opción la usan protocolos heredados como DECNet, OSI TP4 y otros.

Nota El protocolo TCP/IP no admite los datos de conexión en Windows. Los datos de conexión solo se admiten en ATM (RAWWAN) a través de un socket sin procesar.

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 desde el otro socket como parte del establecimiento de la conexión en una estructura WSABUF. El miembro len de la estructura WSABUF a la que apunta el parámetro lpCalleeData contiene inicialmente la longitud del búfer asignado por la aplicación para 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 lpCalleeData será válida cuando se complete la operación de conexión. En el caso de los sockets de bloqueo, la operación de conexión se completa cuando la función WSAConnect devuelve. En el caso de los sockets sin bloqueo, la finalización será después de que se haya producido la notificación de FD_CONNECT. 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 de la conexión, una aplicación puede usar el parámetro lpSQOS y lpGQOS para invalidar cualquier calidad de servicio anterior realizada para el socket a través de WSAIoctl con el código 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 se omitirán, respectivamente, 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 el parámetro lpSQOS indica que no hay calidad de servicio proporcionada por la aplicación.

Reservado para uso futuro con grupos de sockets 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 los sockets conectados 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.

Nota Al emitir una llamada de Winsock de bloqueo como WSAConnect, Winsock puede necesitar esperar un evento de red antes de que se pueda completar la llamada. Winsock realiza una espera alertable en esta situación, que se puede interrumpir mediante una llamada de procedimiento asincrónica (APC) programada en el mismo subproceso. La emisión de otra llamada winsock de bloqueo dentro de un APC que interrumpió una llamada de Winsock de bloqueo en curso en el mismo subproceso provocará un comportamiento indefinido y los clientes winsock nunca deben intentarlo.

Windows Phone 8: esta función es compatible con las aplicaciones de Windows Phone Store en Windows Phone 8 y versiones posteriores.

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