WSAStartup-Funktion (winsock.h)

Artikel
03/13/2024

Die WSAStartup-Funktion initiiert die Verwendung der Winsock-DLL durch einen Prozess.

Syntax

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

Parameter

[in] wVersionRequired

Die höchste Version der Windows Sockets-Spezifikation, die der Aufrufer verwenden kann. Das Byte mit hoher Ordnung gibt die Nebenversionsnummer an. das Byte in niedriger Reihenfolge gibt die Hauptversionsnummer an.

[out] lpWSAData

Ein Zeiger auf die WSADATA-Datenstruktur , die Details zur Windows Sockets-Implementierung empfangen soll.

Rückgabewert

Bei erfolgreicher Ausführung gibt die WSAStartup-Funktion null zurück. Andernfalls wird einer der unten aufgeführten Fehlercodes zurückgegeben.

Die WSAStartup-Funktion gibt direkt den erweiterten Fehlercode im Rückgabewert für diese Funktion zurück. Ein Aufruf der WSAGetLastError-Funktion ist nicht erforderlich und sollte nicht verwendet werden.

Fehlercode	Bedeutung
WSASYSNOTREADY	Das zugrunde liegende Netzwerksubsystem ist nicht bereit für die Netzwerkkommunikation.
WSAVERNOTSUPPORTED	Die angeforderte Version der Windows Sockets-Unterstützung wird von dieser speziellen Windows Sockets-Implementierung nicht bereitgestellt.
WSAEINPROGRESS	Ein blockierende Windows Sockets 1.1-Vorgang wird ausgeführt.
WSAEPROCLIM	Es wurde ein Grenzwert für die Anzahl von Aufgaben erreicht, die von der Windows Sockets-Implementierung unterstützt werden.
WSAEFAULT	Der lpWSAData-Parameter ist kein gültiger Zeiger.

Hinweise

Die WSAStartup-Funktion muss die erste Windows Sockets-Funktion sein, die von einer Anwendung oder DLL aufgerufen wird. Es ermöglicht einer Anwendung oder DLL, die erforderliche Version von Windows Sockets anzugeben und Details zur spezifischen Windows Sockets-Implementierung abzurufen. Die Anwendung oder DLL kann erst nach dem erfolgreichen Aufruf von WSAStartup weitere Windows Sockets-Funktionen ausgeben.

Um verschiedene Windows Sockets-Implementierungen und -Anwendungen zu unterstützen, die funktionale Unterschiede von der neuesten Version der Windows Sockets-Spezifikation aufweisen können, findet in WSAStartup eine Aushandlung statt. Der Aufrufer von WSAStartup übergibt im wVersionRequested-Parameter die höchste Version der Windows Sockets-Spezifikation, die von der Anwendung unterstützt wird. Die Winsock-DLL gibt die höchste Version der Windows Sockets-Spezifikation an, die in der Antwort unterstützt werden kann. Die Winsock-DLL antwortet auch mit der Version der Windows Sockets-Spezifikation, die vom Aufrufer erwartet wird.

Wenn eine Anwendung oder DLL die WSAStartup-Funktion aufruft, überprüft die Winsock-DLL die Version der Windows Sockets-Spezifikation, die von der Anwendung angefordert wurde, die im wVersionRequested-Parameter übergeben wurde . Wenn die von der Anwendung angeforderte Version gleich oder höher ist als die niedrigste Version, die von der Winsock-DLL unterstützt wird, ist der Aufruf erfolgreich, und die Winsock-DLL gibt detaillierte Informationen in der WSADATA-Struktur zurück, auf die der lpWSAData-Parameter verweist. Das wHighVersion-Element der WSADATA-Struktur gibt die höchste Version der Windows Sockets-Spezifikation an, die von der Winsock-DLL unterstützt wird. Der wVersion-Member der WSADATA-Struktur gibt die Version der Windows Sockets-Spezifikation an, die die Winsock-DLL vom Aufrufer erwartet.

Wenn der wVersion-Member der WSADATA-Struktur für den Aufrufer nicht akzeptabel ist, sollte die Anwendung oder DLL WSACleanup aufrufen, um die Winsock-DLL-Ressourcen freizugeben, und die Winsock-Anwendung kann nicht initialisiert werden. Um diese Anwendung oder DLL zu unterstützen, muss nach einer aktualisierten Version der Winsock-DLL gesucht werden, die auf der Plattform installiert werden soll.

Die aktuelle Version der Windows Sockets-Spezifikation ist Version 2.2. Die aktuelle Winsock-DLL Ws2_32.dllunterstützt Anwendungen, die eine der folgenden Versionen der Windows Sockets-Spezifikation anfordern:

Um Vollzugriff auf die neue Syntax einer höheren Version der Windows Sockets-Spezifikation zu erhalten, muss die Anwendung für diese höhere Version verhandeln. In diesem Fall sollte der wVersionRequested-Parameter auf die Anforderung von Version 2.2 festgelegt werden. Die Anwendung muss auch vollständig dieser höheren Version der Windows Socket-Spezifikation entsprechen, z. B. kompilieren mit der entsprechenden Headerdatei, Verknüpfen mit einer neuen Bibliothek oder andere Sonderfälle. Die Winsock2.h-Headerdatei für winsock 2-Unterstützung ist im Microsoft Windows Software Development Kit (SDK) enthalten.

Windows Sockets Version 2.2 wird unter Windows Server 2008, Windows Vista, Windows Server 2003, Windows XP, Windows 2000, Windows NT 4.0 mit Service Pack 4 (SP4) und höher, Windows Me, Windows 98 und Windows 95 OSR2 unterstützt. Windows Sockets Version 2.2 wird auch unter unterstützt.
Windows 95 mit dem Windows Socket 2 Update. Anwendungen auf diesen Plattformen sollten normalerweise Winsock 2.2 anfordern, indem sie den wVersionRequested-Parameter entsprechend festlegen.

Unter Windows 95 und Versionen von Windows NT 3.51 und früher ist Windows Sockets Version 1.1 die höchste unterstützte Version der Windows Sockets-Spezifikation.

Es ist zulässig und möglich, dass eine Anwendung oder DLL, die geschrieben wurde, eine niedrigere Version der Windows Sockets-Spezifikation verwendet, die von der Winsock-DLL unterstützt wird, um diese niedrigere Version mithilfe der WSAStartup-Funktion erfolgreich auszuhandeln . Beispielsweise kann eine Anwendung Version 1.1 im wVersionRequested-Parameter anfordern, der an die WSAStartup-Funktion auf einer Plattform mit der Winsock 2.2-DLL übergeben wird. In diesem Fall sollte sich die Anwendung nur auf Features verlassen, die in die angeforderte Version passen. Neue Ioctl-Codes, neues Verhalten vorhandener Funktionen und neue Funktionen sollten nicht verwendet werden. Die von WSAStartup bereitgestellte Versionsverhandlung wurde hauptsächlich verwendet, um die Ausführung älterer Winsock 1.1-Anwendungen, die für Windows 95 und Windows NT 3.51 und früher entwickelt wurden, mit demselben Verhalten unter späteren Versionen von Windows zu ermöglichen. Die Winsock.h-Headerdatei für winsock 1.1-Unterstützung ist im Windows SDK enthalten.

Diese Aushandlung in der WSAStartup-Funktion ermöglicht sowohl die Anwendung oder DLL, die Windows Sockets verwendet, als auch die Winsock-DLL, um eine Reihe von Windows Sockets-Versionen zu unterstützen. Eine Anwendung oder DLL kann die Winsock-DLL verwenden, wenn es überlappende Versionsbereiche gibt. Ausführliche Informationen zur Windows Sockets-Implementierung finden Sie in der WSADATA-Struktur , die von der WSAStartup-Funktion zurückgegeben wird.

Die folgende Tabelle zeigt, wie WSAStartup mit verschiedenen Anwendungen und Winsock-DLL-Versionen funktioniert.

Unterstützung der Anruferversion	Unterstützung der Winsock-DLL-Version	wVersion angefordert	Zurückgegebene wVersion	Zurückgegebene wHighVersion	Endergebnis
1.1	1.1	1.1	1.1	1.1	Verwenden von 1.1
1.0 1.1	1.0	1.1	1.0	1.0	Verwenden von 1.0
1.0	1.0 1.1	1.0	1.0	1.1	Verwenden von 1.0
1.1	1.0 1.1	1.1	1.1	1.1	Verwenden von 1.1
1.1	1.0	1.1	1.0	1.0	Fehler bei der Anwendung
1.0	1.1	1.0	—	—	WSAVERNOTSUPPORTED
1.0 1.1	1.0 1.1	1.1	1.1	1.1	Verwenden von 1.1
1.1 2.0	1.0 1.1	2.0	1.1	1.1	Verwenden von 1.1
2.0	1.0 1.1 2.0	2.0	2.0	2.0	Verwenden von 2.0
2.0 2.2	1.0 1.1 2.0	2.2	2.0	2.0	Verwenden von 2.0
2.2	1.0 1.1 2.0 2.1 2.2	2.2	2.2	2.2	Verwenden von 2.2

Sobald eine Anwendung oder DLL einen erfolgreichen WSAStartup-Aufruf ausgeführt hat, kann sie bei Bedarf mit anderen Windows Sockets-Aufrufen fortfahren. Wenn die Verwendung der Dienste der Winsock-DLL abgeschlossen ist, muss die Anwendung WSACleanup aufrufen, damit die Winsock-DLL interne Winsock-Ressourcen freigeben kann, die von der Anwendung verwendet werden.

Eine Anwendung kann WSAStartup mehrmals aufrufen, wenn sie die WSADATA-Strukturinformationen mehrmals abrufen muss. Bei jedem solchen Aufruf kann die Anwendung eine beliebige Versionsnummer angeben, die von der Winsock-DLL unterstützt wird.

Die WSAStartup-Funktion führt in der Regel dazu, dass protokollspezifische Hilfs-DLLs geladen werden. Daher sollte die WSAStartup-Funktion nicht über die DllMain-Funktion in einer Anwendungs-DLL aufgerufen werden. Dies kann zu Deadlocks führen. Weitere Informationen finden Sie in der DLL-Hauptfunktion.

Eine Anwendung muss die WSACleanup-Funktion für jedes erfolgreiche Aufrufen der WSAStartup-Funktion aufrufen. Dies bedeutet beispielsweise, dass eine Anwendung WSAStartup dreimal aufruft, WSACleanup dreimal aufrufen muss. Die ersten beiden Aufrufe von WSACleanup führen nichts aus, außer einen internen Zähler zu dekrementieren. Der abschließende WSACleanup-Aufruf für den Task führt alle erforderlichen Ressourcenzuordnungen für den Vorgang aus.

Hinweis Eine Anwendung kann die WSAGetLastError-Funktion aufrufen, um den erweiterten Fehlercode für andere Windows-Socketfunktionen zu ermitteln, wie dies in Windows Sockets üblich ist, auch wenn die WSAStartup-Funktion fehlschlägt oder die WSAStartup-Funktion nicht aufgerufen wurde, um Windows Sockets vor dem Aufrufen einer Windows Sockets-Funktion ordnungsgemäß zu initialisieren. Die WSAGetLastError-Funktion ist eine der einzigen Funktionen in der Winsock 2.2-DLL, die im Falle eines WSAStartup-Fehlers aufgerufen werden kann.

Windows Phone 8: Diese Funktion wird für Windows Phone Store-Apps ab Windows Phone 8 unterstützt.

Windows 8.1 und Windows Server 2012 R2: Diese Funktion wird für Windows Store-Apps auf Windows 8.1, Windows Server 2012 R2 und höher unterstützt.

Beispiele

Das folgende Codefragment veranschaulicht, wie eine Anwendung, die nur Version 2.2 von Windows Sockets unterstützt, einen WSAStartup-Aufruf ausgibt:

#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();

}

Anforderungen

Anforderung	Wert
Unterstützte Mindestversion (Client)	Windows 8.1, Windows Vista [Desktop-Apps \| UWP-Apps]
Unterstützte Mindestversion (Server)	Windows Server 2003 [Desktop-Apps \| UWP-Apps]
Zielplattform	Windows
Kopfzeile	winsock.h (Winsock2.h einschließen)
Bibliothek	Ws2_32.lib
DLL	Ws2_32.dll