Funzione WSAStartup (winsock.h)

Articolo
02/22/2024

La funzione WSAStartup avvia l'uso della DLL Winsock da un processo.

Sintassi

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

Parametri

[in] wVersionRequired

La versione più recente della specifica di Windows Sockets che il chiamante può usare. Il byte di ordine elevato specifica il numero di versione secondaria; il byte con ordine basso specifica il numero di versione principale.

[out] lpWSAData

Puntatore alla struttura di dati WSADATA che deve ricevere i dettagli dell'implementazione di Windows Sockets.

Valore restituito

In caso di esito positivo, la funzione WSAStartup restituisce zero. In caso contrario, restituisce uno dei codici di errore elencati di seguito.

La funzione WSAStartup restituisce direttamente il codice di errore esteso nel valore restituito per questa funzione. Una chiamata alla funzione WSAGetLastError non è necessaria e non deve essere usata.

Codice di errore	Significato
WSASYSNOTREADY	Il sottosistema di rete sottostante non è pronto per la comunicazione di rete.
WSAVERNOTSUPPORTED	La versione del supporto di Windows Sockets richiesta non viene fornita da questa particolare implementazione di Windows Sockets.
WSAEINPROGRESS	È in corso un'operazione di blocco di Windows Sockets 1.1.
WSAEPROCLIM	È stato raggiunto un limite per il numero di attività supportate dall'implementazione di Windows Sockets.
WSAEFAULT	Il parametro lpWSAData non è un puntatore valido.

Commenti

La funzione WSAStartup deve essere la prima funzione Windows Sockets chiamata da un'applicazione o da una DLL. Consente a un'applicazione o a una DLL di specificare la versione di Windows Sockets richiesta e recuperare i dettagli dell'implementazione specifica di Windows Sockets. L'applicazione o la DLL può eseguire altre funzioni di Windows Sockets solo dopo aver chiamato correttamente WSAStartup.

Per supportare varie implementazioni e applicazioni di Windows Sockets che possono avere differenze funzionali rispetto alla versione più recente della specifica di Windows Sockets, viene eseguita una negoziazione in WSAStartup. Il chiamante di WSAStartup passa il parametro wVersionRequested alla versione più alta della specifica Windows Sockets supportata dall'applicazione. La DLL Winsock indica la versione più elevata della specifica di Windows Sockets che può supportare nella risposta. La DLL Winsock risponde anche con la versione della specifica di Windows Sockets che prevede l'uso del chiamante.

Quando un'applicazione o una DLL chiama la funzione WSAStartup , la DLL Winsock esamina la versione della specifica di Windows Sockets richiesta dall'applicazione passata nel parametro wVersionRequested . Se la versione richiesta dall'applicazione è uguale o superiore alla versione più bassa supportata dalla DLL Winsock, la chiamata ha esito positivo e la DLL Winsock restituisce informazioni dettagliate nella struttura WSADATA a cui punta il parametro lpWSAData . Il membro wHighVersion della struttura WSADATA indica la versione più elevata della specifica Windows Sockets supportata dalla DLL Winsock. Il membro wVersion della struttura WSADATA indica la versione della specifica di Windows Sockets che la DLL Winsock prevede che il chiamante usi.

Se il membro wVersion della struttura WSADATA non è accettabile per il chiamante, l'applicazione o la DLL deve chiamare WSACleanup per rilasciare le risorse DLL Winsock e non inizializzare l'applicazione Winsock. Per supportare questa applicazione o DLL, sarà necessario cercare una versione aggiornata della DLL Winsock da installare nella piattaforma.

La versione corrente della specifica di Windows Sockets è la versione 2.2. La DLL Winsock corrente, Ws2_32.dll, supporta le applicazioni che richiedono una delle versioni seguenti della specifica di Windows Sockets:

Per ottenere l'accesso completo alla nuova sintassi di una versione successiva della specifica Windows Sockets, l'applicazione deve negoziare per questa versione successiva. In questo caso, il parametro wVersionRequested deve essere impostato sulla versione 2.2 della richiesta. L'applicazione deve anche essere completamente conforme a tale versione superiore della specifica di Windows Socket, ad esempio la compilazione nel file di intestazione appropriato, il collegamento con una nuova libreria o altri casi speciali. Il file di intestazione Winsock2.h per il supporto di Winsock 2 è incluso in Microsoft Windows Software Development Kit (Windows SDK) (SDK).

Windows Sockets versione 2.2 è supportato in Windows Server 2008, Windows Vista, Windows Server 2003, Windows XP, Windows 2000, Windows NT 4.0 con Service Pack 4 (SP4) e versioni successive, Windows Me, Windows 98 e Windows 95 OSR2. Windows Sockets versione 2.2 è supportato anche in
Windows 95 con Windows Socket 2 Update. Le applicazioni in queste piattaforme devono in genere richiedere Winsock 2.2 impostando di conseguenza il parametro wVersionRequested .

In Windows 95 e versioni di Windows NT 3.51 e versioni precedenti, Windows Sockets versione 1.1 è la versione più recente della specifica Windows Sockets supportata.

È legale e possibile che un'applicazione o una DLL scritta usi una versione inferiore della specifica Windows Sockets supportata dalla DLL Winsock per negoziare correttamente questa versione precedente usando la funzione WSAStartup . Ad esempio, un'applicazione può richiedere la versione 1.1 nel parametro wVersionRequested passato alla funzione WSAStartup in una piattaforma con la DLL Winsock 2.2. In questo caso, l'applicazione deve basarsi solo sulle funzionalità che rientrano nella versione richiesta. Non è consigliabile usare nuovi codici Ioctl, nuovo comportamento delle funzioni esistenti e nuove funzioni. La negoziazione della versione fornita da WSAStartup è stata usata principalmente per consentire l'esecuzione delle applicazioni Winsock 1.1 precedenti sviluppate per Windows 95 e Windows NT 3.51 e versioni precedenti per l'esecuzione con lo stesso comportamento nelle versioni successive di Windows. Il file di intestazione Winsock.h per il supporto di Winsock 1.1 è incluso nel Windows SDK.

Questa negoziazione nella funzione WSAStartup consente sia l'applicazione che la DLL che usa Windows Sockets e la DLL Winsock per supportare una gamma di versioni di Windows Sockets. Un'applicazione o una DLL può usare la DLL Winsock in caso di sovrapposizione negli intervalli di versioni. Le informazioni dettagliate sull'implementazione di Windows Sockets vengono fornite nella struttura WSADATA restituita dalla funzione WSAStartup .

La tabella seguente illustra il funzionamento di WSAStartup con applicazioni diverse e versioni DLL Winsock.

Supporto della versione del chiamante	Supporto della versione dll Winsock	wVersion richiesto	wVersion restituito	wHighVersion restituito	Risultato finale
1,1	1,1	1,1	1,1	1,1	usare 1.1
1.0 1.1	1,0	1,1	1.0	1.0	usare 1.0
1,0	1.0 1.1	1.0	1.0	1,1	usare 1.0
1,1	1.0 1.1	1,1	1,1	1,1	usare 1.1
1,1	1.0	1,1	1.0	1.0	L'applicazione non riesce
1,0	1,1	1.0	—	—	WSAVERNOTSUPPORTED
1.0 1.1	1.0 1.1	1,1	1,1	1,1	usare 1.1
1.1 2.0	1.0 1.1	2,0	1,1	1,1	usare 1.1
2,0	1.0 1.1 2.0	2,0	2,0	2,0	usare 2.0
2.0 2.2	1.0 1.1 2.0	2.2	2,0	2,0	usare 2.0
2.2	1.0 1.1 2.0 2.1 2.2	2.2	2.2	2.2	usare 2.2

Dopo che un'applicazione o una DLL ha effettuato una chiamata WSAStartup riuscita, può procedere per eseguire altre chiamate di Windows Sockets in base alle esigenze. Al termine dell'uso dei servizi della DLL Winsock, l'applicazione deve chiamare WSACleanup per consentire alla DLL Winsock di liberare le risorse winsock interne usate dall'applicazione.

Un'applicazione può chiamare WSAStartup più volte se deve ottenere le informazioni sulla struttura WSADATA più volte. In ogni chiamata, l'applicazione può specificare qualsiasi numero di versione supportato dalla DLL Winsock.

La funzione WSAStartup comporta in genere il caricamento di DLL helper specifiche del protocollo. Di conseguenza, la funzione WSAStartup non deve essere chiamata dalla funzione DllMain in una DLL dell'applicazione. Questo può potenzialmente causare deadlock. Per altre informazioni, vedere la funzione principale della DLL.

Un'applicazione deve chiamare la funzione WSACleanup per ogni esito positivo della chiamata alla funzione WSAStartup . Ciò significa, ad esempio, che se un'applicazione chiama WSAStartup tre volte, deve chiamare WSACleanup tre volte. Le prime due chiamate a WSACleanup non fanno nulla ad eccezione del decremento di un contatore interno; la chiamata WSACleanup finale per l'attività esegue tutta la deallocazione delle risorse necessaria per l'attività.

Nota Un'applicazione può chiamare la funzione WSAGetLastError per determinare il codice di errore esteso per altre funzioni socket di Windows, come avviene normalmente in Windows Sockets anche se la funzione WSAStartup non riesce o la funzione WSAStartup non è stata chiamata per inizializzare correttamente Windows Sockets prima di chiamare una funzione Windows Sockets. La funzione WSAGetLastError è una delle uniche funzioni della DLL Winsock 2.2 che può essere chiamata nel caso di un errore WSAStartup .

Windows Phone 8: questa funzione è supportata per le app Windows Phone Store in Windows Phone 8 e versioni successive.

Windows 8.1 e Windows Server 2012 R2: questa funzione è supportata per le app di Windows Store in Windows 8.1, Windows Server 2012 R2 e versioni successive.

Esempio

Il frammento di codice seguente illustra come un'applicazione che supporta solo la versione 2.2 di Windows Sockets effettua una chiamata 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();

}

Requisiti

Requisito	Valore
Client minimo supportato	Windows 8.1, Windows Vista [app desktop \| App UWP]
Server minimo supportato	Windows Server 2003 [app desktop \| App UWP]
Piattaforma di destinazione	Windows
Intestazione	winsock.h (include Winsock2.h)
Libreria	Ws2_32.lib
DLL	Ws2_32.dll