Función WSAStartup (winsock.h)
La función WSAStartup inicia el uso del archivo DLL de Winsock mediante un proceso.
Sintaxis
int WSAStartup(
[in] WORD wVersionRequired,
[out] LPWSADATA lpWSAData
);
Parámetros
[in] wVersionRequired
La versión más alta de la especificación de Windows Sockets que el autor de la llamada puede usar. El byte de orden superior especifica el número de versión secundaria; el byte de orden bajo especifica el número de versión principal.
[out] lpWSAData
Puntero a la estructura de datos WSADATA que va a recibir detalles de la implementación de Windows Sockets.
Valor devuelto
Si se ejecuta correctamente, la función WSAStartup devuelve cero. De lo contrario, devuelve uno de los códigos de error que se enumeran a continuación.
La función WSAStartup devuelve directamente el código de error extendido en el valor devuelto de esta función. No se necesita una llamada a la función WSAGetLastError y no se debe usar.
| Código de error | Significado |
|---|---|
| El subsistema de red subyacente no está listo para la comunicación de red. | |
| Esta implementación concreta de Windows Sockets no proporciona la versión de soporte técnico de Windows Sockets solicitada. | |
| Está en curso una operación de bloqueo de Windows Sockets 1.1. | |
| Se ha alcanzado un límite en el número de tareas admitidas por la implementación de Windows Sockets. | |
| El parámetro lpWSAData no es un puntero válido. |
Comentarios
La función WSAStartup debe ser la primera función de Windows Sockets a la que llama una aplicación o dll. Permite a una aplicación o DLL especificar la versión de Windows Sockets necesaria y recuperar los detalles de la implementación específica de Windows Sockets. La aplicación o dll solo puede emitir más funciones de Windows Sockets después de llamar correctamente a WSAStartup.
Para admitir varias implementaciones y aplicaciones de Windows Sockets que pueden tener diferencias funcionales con respecto a la última versión de la especificación de Windows Sockets, se realiza una negociación en WSAStartup. El autor de la llamada de WSAStartup pasa al parámetro wVersionRequested la versión más alta de la especificación de Windows Sockets que admite la aplicación. El archivo DLL winsock indica la versión más alta de la especificación de Windows Sockets que puede admitir en su respuesta. El archivo DLL winsock también responde con la versión de la especificación de Windows Sockets que espera que use el autor de la llamada.
Cuando una aplicación o DLL llama a la función WSAStartup , el archivo DLL winsock examina la versión de la especificación de Windows Sockets solicitada por la aplicación pasada en el parámetro wVersionRequested . Si la versión solicitada por la aplicación es igual o superior a la versión más baja admitida por el archivo DLL winsock, la llamada se realiza correctamente y el archivo DLL winsock devuelve información detallada en la estructura WSADATA a la que apunta el parámetro lpWSAData . El miembro wHighVersion de la estructura WSADATA indica la versión más alta de la especificación de Windows Sockets que admite el archivo DLL winsock. El miembro wVersion de la estructura WSADATA indica la versión de la especificación de Windows Sockets que el archivo DLL winsock espera que use el llamador.
Si el miembro wVersion de la estructura WSADATA es inaceptable para el autor de la llamada, la aplicación o dll debe llamar a WSACleanup para liberar los recursos dll de Winsock y no inicializar la aplicación Winsock. Para admitir esta aplicación o DLL, será necesario buscar una versión actualizada del archivo DLL de Winsock para instalar en la plataforma.
La versión actual de la especificación de Windows Sockets es la versión 2.2. El archivo DLL de Winsock actual, Ws2_32.dll, admite aplicaciones que solicitan cualquiera de las siguientes versiones de la especificación de Windows Sockets:
- 1.0
- 1.1
- 2.0
- 2.1
- 2.2
Para obtener acceso completo a la nueva sintaxis de una versión superior de la especificación de Windows Sockets, la aplicación debe negociar esta versión superior. En este caso, el parámetro wVersionRequested debe establecerse en request version 2.2. La aplicación también debe cumplir completamente esa versión superior de la especificación de Windows Socket, como compilar en el archivo de encabezado adecuado, vincular con una nueva biblioteca u otros casos especiales. El archivo de encabezado Winsock2.h para la compatibilidad con Winsock 2 se incluye con Microsoft Kit de desarrollo de software de Windows (SDK).
Windows Sockets versión 2.2 es compatible con Windows Server 2008, Windows Vista, Windows Server 2003, Windows XP, Windows 2000, Windows NT 4.0 con Service Pack 4 (SP4) y versiones posteriores, Windows Me, Windows 98 y Windows 95 OSR2.
Windows Sockets versión 2.2 también se admite en
Windows 95 con la actualización de Windows Socket 2. Las aplicaciones de estas plataformas normalmente deben solicitar Winsock 2.2 estableciendo el parámetro wVersionRequested en consecuencia.
En Windows 95 y versiones de Windows NT 3.51 y versiones anteriores, Windows Sockets versión 1.1 es la versión más alta de la especificación de Windows Sockets admitida.
Es legal y posible que una aplicación o dll escrita use una versión inferior de la especificación de Windows Sockets compatible con el ARCHIVO DLL de Winsock para negociar correctamente esta versión inferior mediante la función WSAStartup . Por ejemplo, una aplicación puede solicitar la versión 1.1 en el parámetro wVersionRequested pasado a la función WSAStartup en una plataforma con el archivo DLL winsock 2.2. En este caso, la aplicación solo debe basarse en características que se ajusten a la versión solicitada. Los nuevos códigos Ioctl, el nuevo comportamiento de las funciones existentes y las nuevas funciones no deben usarse. La negociación de versión proporcionada por WSAStartup se usó principalmente para permitir que las aplicaciones de Winsock 1.1 anteriores desarrolladas para Windows 95 y Windows NT 3.51 y versiones anteriores se ejecutaran con el mismo comportamiento en versiones posteriores de Windows. El archivo de encabezado Winsock.h para la compatibilidad con Winsock 1.1 se incluye con el Windows SDK.
Esta negociación en la función WSAStartup permite que la aplicación o dll que usa Windows Sockets y el ARCHIVO DLL winsock admitan una variedad de versiones de Windows Sockets. Una aplicación o DLL puede usar el archivo DLL winsock si hay alguna superposición en los intervalos de versiones. La información detallada sobre la implementación de Windows Sockets se proporciona en la estructura WSADATA devuelta por la función WSAStartup .
En la tabla siguiente se muestra cómo funciona WSAStartup con diferentes aplicaciones y versiones dll de Winsock.
| Compatibilidad con la versión del autor de la llamada | Compatibilidad con la versión de DLL de Winsock | wVersion solicitado | wVersion devuelto | wHighVersion devuelto | Resultado final |
|---|---|---|---|---|---|
| 1.1 | 1.1 | 1.1 | 1.1 | 1.1 | use 1.1 |
| 1.0 1.1 | 1.0 | 1.1 | 1,0 | 1.0 | use 1.0 |
| 1.0 | 1.0 1.1 | 1.0 | 1.0 | 1.1 | use 1.0 |
| 1.1 | 1.0 1.1 | 1.1 | 1.1 | 1.1 | use 1.1 |
| 1,1 | 1.0 | 1.1 | 1,0 | 1.0 | Error en la aplicación |
| 1.0 | 1.1 | 1,0 | — | — | WSAVERNOTSUPPORTED |
| 1.0 1.1 | 1.0 1.1 | 1.1 | 1.1 | 1.1 | use 1.1 |
| 1.1 2.0 | 1.0 1.1 | 2,0 | 1.1 | 1.1 | use 1.1 |
| 2.0 | 1.0 1.1 2.0 | 2.0 | 2.0 | 2.0 | use 2.0 |
| 2.0 2.2 | 1.0 1.1 2.0 | 2.2 | 2.0 | 2.0 | use 2.0 |
| 2.2 | 1.0 1.1 2.0 2.1 2.2 | 2.2 | 2.2 | 2.2 | use 2.2 |
Una vez que una aplicación o dll ha realizado una llamada de WSAStartup correcta, puede continuar para realizar otras llamadas de Windows Sockets según sea necesario. Cuando haya terminado de usar los servicios del ARCHIVO DLL de Winsock, la aplicación debe llamar a WSACleanup para permitir que el archivo DLL de Winsock libere recursos internos de Winsock usados por la aplicación.
Una aplicación puede llamar a WSAStartup más de una vez si necesita obtener la información de estructura de WSADATA más de una vez. En cada llamada de este tipo, la aplicación puede especificar cualquier número de versión admitido por el ARCHIVO DLL de Winsock.
La función WSAStartup suele dar lugar a que se carguen archivos DLL auxiliares específicos del protocolo. Como resultado, no se debe llamar a la función WSAStartup desde la función DllMain en un archivo DLL de aplicación. Esto puede provocar interbloqueos. Para obtener más información, consulte la función principal de DLL.
Una aplicación debe llamar a la función WSACleanup para cada vez que se llame correctamente a la función WSAStartup . Esto significa, por ejemplo, que si una aplicación llama a WSAStartup tres veces, debe llamar a WSACleanup tres veces. Las dos primeras llamadas a WSACleanup no hacen nada excepto disminuir un contador interno; La llamada WSACleanup final para la tarea realiza toda la desasignación de recursos necesaria para la tarea.
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.
Ejemplos
En el fragmento de código siguiente se muestra cómo una aplicación que solo admite la versión 2.2 de Windows Sockets realiza una llamada WSAStartup :
#define WIN32_LEAN_AND_MEAN
#include <windows.h>
#include <winsock2.h>
#include <ws2tcpip.h>
#include <stdio.h>
// Need to link with Ws2_32.lib
#pragma comment(lib, "ws2_32.lib")
int __cdecl main()
{
WORD wVersionRequested;
WSADATA wsaData;
int err;
/* Use the MAKEWORD(lowbyte, highbyte) macro declared in Windef.h */
wVersionRequested = MAKEWORD(2, 2);
err = WSAStartup(wVersionRequested, &wsaData);
if (err != 0) {
/* Tell the user that we could not find a usable */
/* Winsock DLL. */
printf("WSAStartup failed with error: %d\n", err);
return 1;
}
/* Confirm that the WinSock DLL supports 2.2.*/
/* Note that if the DLL supports versions greater */
/* than 2.2 in addition to 2.2, it will still return */
/* 2.2 in wVersion since that is the version we */
/* requested. */
if (LOBYTE(wsaData.wVersion) != 2 || HIBYTE(wsaData.wVersion) != 2) {
/* Tell the user that we could not find a usable */
/* WinSock DLL. */
printf("Could not find a usable version of Winsock.dll\n");
WSACleanup();
return 1;
}
else
printf("The Winsock 2.2 dll was found okay\n");
/* The Winsock DLL is acceptable. Proceed to use it. */
/* Add network programming using Winsock here */
/* then call WSACleanup when done using the Winsock dll */
WSACleanup();
}
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 | winsock.h (incluya Winsock2.h) |
| Library | Ws2_32.lib |
| Archivo DLL | Ws2_32.dll |