función connect (winsock2.h)

Artículo
08/27/2023

La función connect establece una conexión a un socket especificado.

Sintaxis

int WSAAPI connect(
  [in] SOCKET         s,
  [in] const sockaddr *name,
  [in] int            namelen
);

Parámetros

[in] s

Descriptor que identifica un socket no conectado.

[in] name

Puntero a la estructura sockaddr a la que se debe establecer la conexión.

[in] namelen

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

Valor devuelto

Si no se produce ningún error, connect devuelve cero. De lo contrario, devuelve SOCKET_ERROR 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 el intento de conexión se ha realizado correctamente o no.

Con un socket sin bloqueo, el intento de conexión no se puede completar inmediatamente. En este caso, connect devolverá SOCKET_ERROR y WSAGetLastError devolverá WSAEWOULDBLOCK. En este caso, hay tres escenarios posibles:

Use la función 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 que indica que la operación de conexión se ha completado (correctamente 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á que la operación de conexión se ha completado (correctamente o no).

Hasta que se complete el intento de conexión en un socket sin bloqueo, todas las llamadas posteriores para conectarse en el mismo socket producirán un error con el código de error WSAEALREADY y WSAEISCONN cuando la conexión se complete correctamente. Debido a ambigüedades en la versión 1.1 de la especificación de Windows Sockets, los códigos de error devueltos de la conexión mientras que una conexión ya está pendiente puede variar entre las implementaciones. Como resultado, no se recomienda que las aplicaciones usen varias llamadas para conectarse para detectar la finalización de la conexión. Si lo hacen, deben estar preparados para controlar los valores de error WSAEINVAL y WSAEWOULDBLOCK de la misma manera que controlan WSAEALREADY, para garantizar una operación sólida.

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 connect de nuevo para el mismo socket.

Código de error	Significado
WSANOTINITIALISED	Debe producirse una llamada 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 al ejecutar el enlace, pero podría retrasarse hasta que la función connect si el enlace fuera a una dirección comodín (INADDR_ANY o in6addr_any) para la dirección IP local. La función connect debe enlazar implícitamente una dirección específica.
WSAEINTR	La llamada de Bloqueo de Windows Socket 1.1 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 está en curso en el socket especificado. Nota 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 Wsock32.dll.
WSAEADDRNOTAVAIL	La dirección remota no es una dirección válida (como INADDR_ANY o in6addr_any).
WSAEAFNOSUPPORT	Las direcciones de la familia especificada no se pueden usar con este socket.
WSAECONNREFUSED	El intento de conexión se rechazó con fuerza.
WSAEFAULT	La estructura sockaddr a la que apunta el nombre contiene un formato de dirección incorrecto para la familia de direcciones asociada o el parámetro namelen es demasiado pequeño. Este error también se devuelve si la estructura sockaddr a la que apunta el parámetro name con una longitud especificada en el parámetro namelen no está en una parte válida del espacio de direcciones del usuario.
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.
WSAEHOSTUNREACH	Se intentó realizar una operación de socket a un host inalcanzable.
WSAENOBUFS	Nota No hay espacio de búfer disponible. El socket no se puede conectar.
WSAENOTSOCK	El descriptor especificado en el parámetro s no es un socket.
WSAETIMEDOUT	Se agota el tiempo de espera de la conexión sin 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 un socket de datagrama a la dirección de difusión porque la opción setsockopt SO_BROADCAST no está habilitada.

Comentarios

La función connect se usa para crear una conexión al destino especificado. Si el socket 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 externo mediante el nombre (una dirección en el espacio de nombres del socket; para obtener una descripción detallada, vea bind y sockaddr).

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.

Cuando la llamada al socket se completa correctamente, el socket está listo para enviar y recibir datos. Si el miembro de dirección de la estructura especificada por el parámetro name se rellena con ceros, connect 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 sockets orientados a la conexión y sin bloqueo, a menudo no es posible completar la conexión inmediatamente. En tal caso, esta función devuelve el error WSAEWOULDBLOCK. Sin embargo, la operación continúa.

Cuando se conoce el resultado de éxito o error, se puede notificar de una de estas dos maneras, dependiendo de cómo se registre el cliente para la notificación.

Si el cliente usa la función select , se notifica si se ha realizado correctamente en el conjunto writefds y se notifica un error en el conjunto exceptfds.
Si el cliente usa las funciones 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.

Si la conexión no se completa inmediatamente, el cliente debe esperar a que finalice la conexión antes de intentar establecer las opciones de socket mediante setsockopt. No se admite la llamada a setsockopt mientras una conexión está en curso.

Para un socket sin conexión (por ejemplo, tipo SOCK_DGRAM), la operación realizada por connect es simplemente establecer una dirección de destino predeterminada que se puede usar en llamadasWSASend y recv/ WSARecv de envío/ posteriores. 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 especificada por nombre se rellena con ceros, el socket se desconectará. A continuación, la dirección remota predeterminada será indeterminada, por lo que enviar/ llamadasWSASend y recv/ WSARecv devolverán el código de error WSAENOTCONN. Sin embargo, todavía se puede usar sendto/ WSASendTo y recvfrom/ WSARecvFrom . El destino predeterminado se puede cambiar simplemente llamando a connect de nuevo, incluso si el socket ya está conectado. Los datagramas en cola para recibir se descartan si el nombre es diferente de la conexión 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 usar setsockopt para habilitar la opción SO_BROADCAST. De lo contrario, se producirá un error en la conexión con el código de error WSAEACCES.

Cuando se interrumpe una conexión entre sockets, se debe descartar el socket conectado y se debe crear un nuevo socket. Cuando un problema se desarrolla en un socket conectado, la aplicación debe descartar el socket y volver a crear el socket para volver a un punto estable.

Nota Al emitir una llamada de Winsock de bloqueo como connect, Winsock puede que tenga que 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.

Código de ejemplo

En el ejemplo siguiente se muestra el uso de la función connect .

#ifndef UNICODE
#define UNICODE
#endif

#define WIN32_LEAN_AND_MEAN

#include <winsock2.h>
#include <ws2tcpip.h>
#include <stdio.h>

// Need to link with Ws2_32.lib
#pragma comment(lib, "ws2_32.lib")

int wmain()
{
    //----------------------
    // Initialize Winsock
    WSADATA wsaData;
    int iResult = WSAStartup(MAKEWORD(2, 2), &wsaData);
    if (iResult != NO_ERROR) {
        wprintf(L"WSAStartup function failed with error: %d\n", iResult);
        return 1;
    }
    //----------------------
    // Create a SOCKET for connecting to server
    SOCKET ConnectSocket;
    ConnectSocket = socket(AF_INET, SOCK_STREAM, IPPROTO_TCP);
    if (ConnectSocket == INVALID_SOCKET) {
        wprintf(L"socket function failed with error: %ld\n", WSAGetLastError());
        WSACleanup();
        return 1;
    }
    //----------------------
    // The sockaddr_in structure specifies the address family,
    // IP address, and port of the server to be connected to.
    sockaddr_in clientService;
    clientService.sin_family = AF_INET;
    clientService.sin_addr.s_addr = inet_addr("127.0.0.1");
    clientService.sin_port = htons(27015);

    //----------------------
    // Connect to server.
    iResult = connect(ConnectSocket, (SOCKADDR *) & clientService, sizeof (clientService));
    if (iResult == SOCKET_ERROR) {
        wprintf(L"connect function failed with error: %ld\n", WSAGetLastError());
        iResult = closesocket(ConnectSocket);
        if (iResult == SOCKET_ERROR)
            wprintf(L"closesocket function failed with error: %ld\n", WSAGetLastError());
        WSACleanup();
        return 1;
    }

    wprintf(L"Connected to server.\n");

    iResult = closesocket(ConnectSocket);
    if (iResult == SOCKET_ERROR) {
        wprintf(L"closesocket function failed with error: %ld\n", WSAGetLastError());
        WSACleanup();
        return 1;
    }

    WSACleanup();
    return 0;
}

Para ver otro ejemplo que usa la función connect, consulte Introducción With Winsock.

Notas para sockets IrDA

El archivo de encabezado Af_irda.h debe incluirse explícitamente.
Si se detecta una conexión IrDA existente en el nivel de acceso multimedia, se devuelve WSAENETDOWN .
Si existen conexiones activas a un dispositivo con una dirección diferente, se devuelve WSAEADDRINUSE .
Si el socket ya está conectado o se produjo un error en el cambio de modo exclusivo o multiplexado, se devuelve WSAEISCONN .
Si el socket se ha enlazado previamente a un nombre de servicio local para aceptar conexiones entrantes mediante bind, se devuelve WSAEINVAL . Tenga en cuenta que una vez que un socket está enlazado, no se puede usar para establecer una conexión saliente.

IrDA implementa la función connect con direcciones del formulario sockaddr_irda. Normalmente, una aplicación cliente creará un socket con la función socket, examinará las proximidades inmediatas de los dispositivos IrDA con la opción de socket IRLMP_ENUMDEVICES, elija un dispositivo de la lista devuelta, forme una dirección y, a continuación, llame a connect. No hay ninguna diferencia entre la semántica de bloqueo y no bloqueo.

Requisitos


Cliente mínimo compatible	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