Fonction WSAStartup (winsock2.h)

La fonction WSAStartup initie l’utilisation de la DLL Winsock par un processus.

Syntaxe

int WSAAPI WSAStartup(
  [in]  WORD      wVersionRequested,
  [out] LPWSADATA lpWSAData
);

Paramètres

[in] wVersionRequested

Version la plus élevée de la spécification des sockets Windows que l’appelant peut utiliser. L’octet d’ordre élevé spécifie le numéro de version mineure ; l’octet de faible ordre spécifie le numéro de version principale.

[out] lpWSAData

Pointeur vers la structure de données WSADATA qui doit recevoir les détails de l’implémentation des sockets Windows.

Valeur retournée

Si elle réussit, la fonction WSAStartup retourne zéro. Sinon, il retourne l’un des codes d’erreur répertoriés ci-dessous.

La fonction WSAStartup retourne directement le code d’erreur étendu dans la valeur de retour de cette fonction. Un appel à la fonction WSAGetLastError n’est pas nécessaire et ne doit pas être utilisé.

Remarques

La fonction WSAStartup doit être la première fonction Windows Sockets appelée par une application ou une DLL. Il permet à une application ou à une DLL de spécifier la version des sockets Windows requise et de récupérer les détails de l’implémentation spécifique des sockets Windows. L’application ou la DLL ne peut émettre d’autres fonctions de sockets Windows qu’après avoir correctement appelé WSAStartup.

Afin de prendre en charge différentes implémentations et applications Windows Sockets qui peuvent présenter des différences fonctionnelles par rapport à la dernière version de la spécification des sockets Windows, une négociation a lieu dans WSAStartup. L’appelant de WSAStartup transmet au paramètre wVersionRequested la version la plus élevée de la spécification Windows Sockets prise en charge par l’application. La DLL Winsock indique la version la plus élevée de la spécification des sockets Windows qu’elle peut prendre en charge dans sa réponse. La DLL Winsock répond également avec la version de la spécification des sockets Windows qu’elle attend de l’appelant à utiliser.

Lorsqu’une application ou une DLL appelle la fonction WSAStartup , la DLL Winsock examine la version de la spécification des sockets Windows demandée par l’application passée dans le paramètre wVersionRequested . Si la version demandée par l’application est égale ou supérieure à la version la plus basse prise en charge par la DLL Winsock, l’appel réussit et la DLL Winsock retourne des informations détaillées dans la structure WSADATA pointée vers le paramètre lpWSAData . Le membre wHighVersion de la structure WSADATA indique la version la plus élevée de la spécification windows Sockets prise en charge par la DLL Winsock. Le membre wVersion de la structure WSADATA indique la version de la spécification des sockets Windows que la DLL Winsock s’attend à ce que l’appelant utilise.

Si le membre wVersion de la structure WSADATA n’est pas acceptable pour l’appelant, l’application ou la DLL doit appeler WSACleanup pour libérer les ressources de la DLL Winsock et ne pas initialiser l’application Winsock. Pour prendre en charge cette application ou dll, il sera nécessaire de rechercher une version mise à jour de la DLL Winsock à installer sur la plateforme.

La version actuelle de la spécification des sockets Windows est la version 2.2. La DLL Winsock actuelle, Ws2_32.dll, prend en charge les applications qui demandent l’une des versions suivantes de la spécification des sockets Windows :

• 1.0
• 1.1
• 2.0
• 2.1
• 2.2

Pour obtenir un accès complet à la nouvelle syntaxe d’une version supérieure de la spécification des sockets Windows, l’application doit négocier pour cette version supérieure. Dans ce cas, le paramètre wVersionRequested doit être défini pour demander la version 2.2. L’application doit également être entièrement conforme à cette version supérieure de la spécification du socket Windows, comme la compilation sur le fichier d’en-tête approprié, la liaison avec une nouvelle bibliothèque ou d’autres cas spéciaux. Le fichier d’en-tête Winsock2.h pour la prise en charge de Winsock 2 est inclus dans le Kit de développement logiciel (SDK) Microsoft Windows.

Les sockets Windows version 2.2 sont pris en charge sur Windows Server 2008, Windows Vista, Windows Server 2003, Windows XP, Windows 2000, Windows NT 4.0 avec Service Pack 4 (SP4) et versions ultérieures, Windows Me, Windows 98 et Windows 95 OSR2. Les sockets Windows version 2.2 sont également pris en charge sur
Windows 95 avec Windows Socket 2 Update. Les applications sur ces plateformes doivent normalement demander Winsock 2.2 en définissant le paramètre wVersionRequested en conséquence.

Sur Windows 95 et les versions de Windows NT 3.51 et versions antérieures, windows Sockets version 1.1 est la version la plus élevée de la spécification des sockets Windows prise en charge.

Il est légal et possible qu’une application ou une DLL écrite utilise une version inférieure de la spécification des sockets Windows prise en charge par la DLL Winsock pour négocier correctement cette version inférieure à l’aide de la fonction WSAStartup . Par exemple, une application peut demander la version 1.1 dans le paramètre wVersionRequested passé à la fonction WSAStartup sur une plateforme avec la DLL Winsock 2.2. Dans ce cas, l’application ne doit s’appuyer que sur les fonctionnalités qui correspondent à la version demandée. Les nouveaux codes Ioctl, le nouveau comportement des fonctions existantes et les nouvelles fonctions ne doivent pas être utilisés. La négociation de version fournie par WSAStartup était principalement utilisée pour permettre aux applications Winsock 1.1 plus anciennes développées pour Windows 95 et Windows NT 3.51 et versions antérieures de s’exécuter avec le même comportement sur les versions ultérieures de Windows. Le fichier d’en-tête Winsock.h pour la prise en charge de Winsock 1.1 est inclus dans le KIT de développement logiciel (SDK) Windows.

Cette négociation dans la fonction WSAStartup permet à l’application ou à la DLL qui utilise des sockets Windows et la DLL Winsock de prendre en charge une gamme de versions de sockets Windows. Une application ou une DLL peut utiliser la DLL Winsock si les plages de versions se chevauchent. Des informations détaillées sur l’implémentation des sockets Windows sont fournies dans la structure WSADATA retournée par la fonction WSAStartup .

Le tableau suivant montre comment WSAStartup fonctionne avec différentes applications et versions de DLL Winsock.

Une fois qu’une application ou une DLL a effectué un appel WSAStartup réussi, elle peut effectuer d’autres appels de sockets Windows en fonction des besoins. Une fois qu’elle a terminé d’utiliser les services de la DLL Winsock, l’application doit appeler WSACleanup pour permettre à la DLL Winsock de libérer les ressources Winsock internes utilisées par l’application.

Une application peut appeler WSAStartup plusieurs fois si elle a besoin d’obtenir les informations de structure WSADATA plusieurs fois. À chaque appel de ce type, l’application peut spécifier n’importe quel numéro de version pris en charge par la DLL Winsock.

La fonction WSAStartup entraîne généralement le chargement de DLL d’assistance spécifiques au protocole. Par conséquent, la fonction WSAStartup ne doit pas être appelée à partir de la fonction DllMain dans une DLL d’application. Cela peut potentiellement provoquer des blocages. Pour plus d’informations, consultez la fonction principale DE DLL.

Une application doit appeler la fonction WSACleanup pour chaque fois que la fonction WSAStartup est appelée avec succès. Cela signifie, par exemple, que si une application appelle WSAStartup trois fois, elle doit appeler WSACleanup trois fois. Les deux premiers appels à WSACleanup ne font rien sauf décrémenter un compteur interne ; l’appel WSACleanup final pour la tâche effectue toutes les allocations de ressources nécessaires pour la tâche.

Windows Phone 8 : cette fonction est prise en charge pour les applications du Store Windows Phone Windows Phone 8 et versions ultérieures.

Windows 8.1 et Windows Server 2012 R2 : cette fonction est prise en charge pour les applications du Windows Store sur Windows 8.1, Windows Server 2012 R2 et versions ultérieures.

Exemples

Le fragment de code suivant montre comment une application qui prend uniquement en charge la version 2.2 des sockets Windows effectue un appel 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();

}

Configuration requise

Voir aussi

MAKEWORD

WSACleanup

WSAGetLastError

Fonctions Winsock

Informations de référence sur Winsock

envoyer

Sendto