Partager via

WSAStartup, fonction (winsock.h)

  • Article

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

Syntaxe

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

Paramètres

[in] wVersionRequired

Version la plus élevée de la spécification Windows Sockets que l’appelant peut utiliser. L’octet d’ordre supérieur spécifie le numéro de version mineure ; l’octet d’ordre inférieur 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 de Windows Sockets.

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é.

Code d'erreur Signification
WSASYSNOTREADY
 Le sous-système réseau sous-jacent n’est pas prêt pour la communication réseau.
WSAVERNOTSUPPORTED
 La version de la prise en charge de Windows Sockets demandée n’est pas fournie par cette implémentation windows sockets particulière.
WSAEINPROGRESS
 Une opération windows sockets 1.1 bloquante est en cours.
WSAEPROCLIM
 Une limite du nombre de tâches prises en charge par l’implémentation de Windows Sockets a été atteinte.
WSAEFAULT
 Le paramètre lpWSAData n’est pas un pointeur valide.

Remarques

La fonction WSAStartup doit être la première fonction Windows Sockets appelée par une application ou une DLL. Elle 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 windows sockets spécifique. L’application ou la DLL ne peut émettre d’autres fonctions Windows Sockets qu’après avoir correctement appelé WSAStartup.

Pour prendre en charge diverses implémentations et applications Windows Sockets qui peuvent présenter des différences fonctionnelles par rapport à la dernière version de la spécification Windows Sockets, 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 Windows Sockets qu’elle peut prendre en charge dans sa réponse. La DLL Winsock répond également avec la version de la spécification Windows Sockets qu’elle s’attend à ce que l’appelant utilise.

Lorsqu’une application ou une DLL appelle la fonction WSAStartup , la DLL Winsock examine la version de la spécification Windows Sockets 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 Windows Sockets que la DLL Winsock attend que l’appelant utilise.

Si le membre wVersion de la structure WSADATA est inacceptable 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 Windows Sockets 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 Windows Sockets :

  • 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 Windows Sockets, l’application doit négocier 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 windows Socket, 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 microsoft Kit de développement logiciel Windows (Kit SDK Windows) (SDK).

Windows Sockets version 2.2 est 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. Windows Sockets version 2.2 est é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 Windows Sockets 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 Windows Sockets 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 doit s’appuyer uniquement 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 a été 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 SDK Windows.

Cette négociation dans la fonction WSAStartup permet à l’application ou à la DLL qui utilise Windows Sockets et la DLL Winsock de prendre en charge une plage de versions de Windows Sockets. Une application ou une DLL peut utiliser la DLL Winsock en cas de chevauchement dans les plages de versions. Des informations détaillées sur l’implémentation de Windows Sockets 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.

Prise en charge de la version de l’appelant Prise en charge des versions de DLL Winsock wVersion demandée wVersion retourné wHighVersion retourné Résultat final
1.1 1.1 1.1 1.1 1.1 utiliser 1.1
1.0 1.1 1.0 1.1 1.0 1.0 utiliser 1.0
1.0 1.0 1.1 1.0 1.0 1.1 utiliser 1.0
1.1 1.0 1.1 1.1 1.1 1.1 utiliser 1.1
1.1 1.0 1.1 1.0 1.0 L’application échoue
1.0 1.1 1.0 — — WSAVERNOTSUPPORTED
1.0 1.1 1.0 1.1 1.1 1.1 1.1 utiliser 1.1
1.1 2.0 1.0 1.1 2,0 1.1 1.1 utiliser 1.1
2.0 1.0 1.1 2.0 2.0 2.0 2.0 utiliser 2.0
2.0 2.2 1.0 1.1 2.0 2.2 2.0 2.0 utiliser 2.0
2.2 1.0 1.1 2.0 2.1 2.2 2.2 2.2 2.2 utiliser 2.2
 

Une fois qu’une application ou une DLL a effectué un appel WSAStartup réussi, elle peut effectuer d’autres appels Windows Sockets si nécessaire. 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 doit obtenir plusieurs fois les informations de structure WSADATA . À 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 entraîner des interblocages. Pour plus d’informations, consultez la fonction principale DE DLL.

Une application doit appeler la fonction WSACleanup pour chaque appel réussi de la fonction WSAStartup . 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 d’autre que décrémenter un compteur interne ; L’appel WSACleanup final pour la tâche effectue toutes les désallocations de ressources nécessaires pour la tâche.

Note Une application peut appeler la fonction WSAGetLastError pour déterminer le code d’erreur étendu pour d’autres fonctions de sockets Windows, comme cela se fait normalement dans les sockets Windows, même si la fonction WSAStartup échoue ou si la fonction WSAStartup n’a pas été appelée pour initialiser correctement les sockets Windows avant d’appeler une fonction Windows Sockets. La fonction WSAGetLastError est l’une des seules fonctions de la DLL Winsock 2.2 qui peut être appelée en cas d’échec de WSAStartup .
 

Windows Phone 8 : cette fonction est prise en charge pour les applications Windows Phone Store sur 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 en charge uniquement la version 2.2 de Windows Sockets 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

Condition requise Valeur
Client minimal pris en charge Windows 8.1, Windows Vista [applications de bureau | Applications UWP]
Serveur minimal pris en charge Windows Server 2003 [applications de bureau | applications UWP]
Plateforme cible Windows
En-tête winsock.h (inclure Winsock2.h)
Bibliothèque Ws2_32.lib
DLL Ws2_32.dll

Voir aussi

MAKEWORD

WSACleanup

WSAGetLastError

Winsock Functions

Référence Winsock

envoyer

Sendto