Funzione WSAStartup (winsock.h)
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 |
|---|---|
| Il sottosistema di rete sottostante non è pronto per la comunicazione di rete. | |
| La versione del supporto di Windows Sockets richiesta non viene fornita da questa particolare implementazione di Windows Sockets. | |
| È in corso un'operazione di blocco di Windows Sockets 1.1. | |
| È stato raggiunto un limite per il numero di attività supportate dall'implementazione di Windows Sockets. | |
| 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:
- 1,0
- 1,1
- 2.0
- 2.1
- 2.2
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à.
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 |
Vedi anche
Commenti e suggerimenti
Presto disponibile: Nel corso del 2024 verranno gradualmente disattivati i problemi di GitHub come meccanismo di feedback per il contenuto e ciò verrà sostituito con un nuovo sistema di feedback. Per altre informazioni, vedere https://aka.ms/ContentUserFeedback.
Invia e visualizza il feedback per