Función WSAConnect (winsock2.h)
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).
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 |
|---|---|
| Debe producirse una llamada de WSAStartup correcta antes de usar esta función. | |
| Error en el subsistema de red. | |
| 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. | |
| La llamada a Windows Socket 1.1 (bloqueo) se canceló 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. | |
| Una llamada de conexión sin bloqueo o WSAConnect está en curso en el socket especificado. | |
| 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. | |
| El intento de conexión se rechazó. | |
| 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. | |
| 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. | |
| El socket ya está conectado (solo sockets orientados a la conexión). | |
| La red no se puede alcanzar desde este host en estos momentos. | |
| Se intentó realizar una operación de socket a un host inalcanzable. | |
| No hay espacio disponible en el búfer. El socket no se puede conectar. | |
| El descriptor no es un socket. | |
| No se pueden satisfacer las estructuras FLOWSPEC especificadas en lpSQOS y lpGQOS . | |
| El proveedor de servicios no admite el parámetro lpCallerData . | |
| Se ha agotado el tiempo de espera de la conexión sin poder establecer una conexión. | |
| El socket está marcado como de no bloqueo y la conexión no puede completarse inmediatamente. | |
| 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.
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.
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.
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 |