WSPStartup-Funktion (ws2spi.h)
Die WSPStartup-Funktion initiiert die Verwendung einer Windows Sockets-Dienstanbieterschnittstelle (SPI) durch einen Client.
Syntax
int WSPStartup(
[in] WORD wVersionRequested,
[out] LPWSPDATA lpWSPData,
[in] LPWSAPROTOCOL_INFOW lpProtocolInfo,
[in] WSPUPCALLTABLE UpcallTable,
[out] LPWSPPROC_TABLE lpProcTable
);
Parameter
[in] wVersionRequested
Die höchste Version von Windows Sockets SPI-Unterstützung, die der Aufrufer verwenden kann. Das hochgeordnete Byte gibt die Nebenversionsnummer (Revisionsnummer) an. das Byte mit niedriger Reihenfolge gibt die Hauptversionsnummer an.
[out] lpWSPData
Ein Zeiger auf eine WSPDATA-Datenstruktur , die Informationen zum Windows Sockets-Dienstanbieter empfängt.
[in] lpProtocolInfo
Ein Zeiger auf eine WSAProtocol_Info-Struktur , die die Merkmale des gewünschten Protokolls definiert. Dies ist besonders nützlich, wenn eine einzelne Anbieter-DLL in der Lage ist, mehrere verschiedene Dienstanbieter zu instanziieren.
[in] UpcallTable
Die Winsock 2-DLL(Ws2_32.dll)-Upcall-Verteilungstabelle, die in einer WSPUpCallTable-Struktur übergeben wurde.
[out] lpProcTable
Ein Zeiger auf die Tabelle der SPI-Funktionszeiger. Diese Tabelle wird als WSPProc_Table-Struktur zurückgegeben.
Rückgabewert
Die WSPStartup-Funktion gibt bei erfolgreicher Ausführung null zurück. Andernfalls wird einer der unten aufgeführten Fehlercodes zurückgegeben.
| Fehlercode | Bedeutung |
|---|---|
| Das Netzwerksubsystem ist nicht verfügbar. Dieser Fehler wird zurückgegeben, wenn die Windows Sockets-Implementierung zu diesem Zeitpunkt nicht funktionieren kann, da das zugrunde liegende System, das zur Bereitstellung von Netzwerkdiensten verwendet wird, derzeit nicht verfügbar ist. | |
| Die Winsock.dll Version liegt außerhalb des Bereichs. Dieser Fehler wird zurückgegeben, wenn die angeforderte Version der Windows Sockets SPI-Unterstützung nicht von diesem speziellen Windows Sockets-Dienstanbieter bereitgestellt wird. | |
| Ein blockierende Windows Sockets 1.1-Vorgang wird ausgeführt. | |
| Die Anzahl der von der Windows Sockets-Implementierung unterstützten Aufgaben wurde überschritten. | |
| Der Parameter lpWSPData oder lpProcTable ist ungültig. |
Hinweise
Windows Sockets 2-Transportdienstanbieter sind DLLs mit einem einzelnen exportierten Prozedureinstiegspunkt, WSPStartup, der für die Initialisierungsfunktion des Dienstanbieters verwendet wird. Alle anderen Dienstanbieterfunktionen werden für die Winsock 2-DLL über die Dispatchtabelle des Dienstanbieters zugänglich gemacht, die im lpProcTable-Parameter an die WSPStartup-Funktion übergeben wird. Dienstanbieter-DLL's werden von der WinSock 2-DLL nur bei Bedarf in den Arbeitsspeicher geladen und entladen, wenn ihre Dienste nicht mehr erforderlich sind.
Die Dienstanbieterschnittstelle definiert auch mehrere Umstände, unter denen ein Transportdienstanbieter in die Winsock 2-DLL (Upcalls) aufruft, um DLL-Unterstützungsdienste abzurufen. Der Transportdienstanbieter gibt die Upcall-Verteilertabelle für die Winsock 2-DLL im UpcallTable-Parameter zurück, der an die WSPStartup-Funktion übergeben wird.
Die WSPStartup-Funktion muss die erste SPI-Funktion von Windows Sockets sein, die von einem Windows Sockets SPI-Client pro Prozess aufgerufen wird. Dadurch kann der Client die erforderliche Version von Windows Sockets SPI angeben und die Tabelle für die Bereitstellung der Upcall-Verteilung bereitstellen. Alle Upcalls (d. h. Funktionen mit dem Präfix WPU), die vom Windows Sockets-Dienstanbieter ausgeführt werden, werden über die Upcall-Verteilungstabelle des Clients aufgerufen. Diese Funktion ermöglicht es dem Client auch, Details der spezifischen Windows Sockets-Dienstanbieterimplementierung abzurufen. Der Windows Sockets SPI-Client kann erst nach einem erfolgreichen WSPStartup-Aufruf weitere Spi-Funktionen von Windows Sockets ausstellen. Eine Tabelle mit Zeigern auf die restlichen SPI-Funktionen wird über den lpProcTable-Parameter abgerufen, der eine WSPProc_Table Struktur zurückgibt.
Die Winsock 2-DLL lädt die Schnittstellen-DLL des Dienstanbieters mithilfe der standardmäßigen Dynamischen Windows-Bibliothekslademechanismen in das System und initialisiert sie durch Aufrufen der WSPStartup-Funktion . Dies wird in der Regel durch eine Anwendung ausgelöst, die die Socket- oder WSASocket-Funktion aufruft, um einen neuen Socket zu erstellen, der einem Dienstanbieter zugeordnet werden soll, dessen Schnittstellen-DLL derzeit nicht in den Arbeitsspeicher geladen wird.
Um zukünftige Versionen des Windows Sockets SPI und der Ws2_32.dll zu unterstützen, die möglicherweise funktionale Unterschiede zum aktuellen Windows Sockets SPI aufweisen, findet eine Aushandlung in WSPStartup statt. Der Aufrufer von WSPStartup (entweder das Ws2_32.dll oder ein mehrschichtiges Protokoll) und der Windows Sockets-Dienstanbieter geben einander die höchste Version von Windows Sockets an, die sie unterstützen können, und bestätigen jeweils, dass die höchste Version des anderen akzeptabel ist. Beim Einstieg in WSPStartup überprüft der Windows Sockets-Dienstanbieter die vom Client angeforderte Version. Wenn diese Version gleich oder höher als die niedrigste Version ist, die vom Dienstanbieter unterstützt wird, wird der Aufruf erfolgreich ausgeführt, und der Dienstanbieter gibt im wHighVersion-Member der WSPDATA-Struktur die höchste version zurück, die er unterstützt, und im wVersion-Member das Minimum seiner hohen Version und Version, die im wVersionRequested-Parameter angegeben ist. Der Windows Sockets-Dienstanbieter geht dann davon aus, dass der Windows Sockets SPI-Client die version von Windows Sockets verwendet, die im wVersion-Member angegeben ist. Wenn das wVersion-Element der WSPDATA-Struktur für den Aufrufer inakzeptabel ist, sollte er LPWSPCleanup aufrufen und entweder nach einem anderen Windows Sockets-Dienstanbieter suchen oder nicht initialisieren.
Diese Aushandlung ermöglicht es sowohl einem Windows Sockets-Dienstanbieter als auch einem Windows Sockets SPI-Client, eine Reihe von Windows Sockets-Versionen zu unterstützen. Ein Client kann erfolgreich einen Windows Sockets-Dienstanbieter verwenden, wenn es eine Überlappung in den Versionsbereichen gibt.
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:
- 1.0
- 1.1
- 2.0
- 2.1
- 2.2
Um vollständigen Zugriff auf die neue Syntax einer höheren Version der Windows Sockets-Spezifikation zu erhalten, muss die Anwendung diese höhere Version aushandeln. In diesem Fall sollte der wVersionRequested-Parameter auf die Anforderung von Version 2.2 festgelegt werden. Die Anwendung muss auch vollständig mit dieser höheren Version der Windows Socket-Spezifikation übereinstimmen, 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 legal 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 WSPStartup-Funktion erfolgreich auszuhandeln . Beispielsweise kann eine Anwendung Version 1.1 im wVersionRequested-Parameter anfordern, der an die WSPStartup-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 vom WSPStartup bereitgestellte Versionsverhandlung wurde hauptsächlich verwendet, um älteren Winsock 1.1-Anwendungen, die für Windows 95 und Windows NT 3.51 und früher entwickelt wurden, die Ausführung mit dem gleichen Verhalten unter höheren Versionen von Windows zu ermöglichen. Die Winsock.h-Headerdatei für Winsock 1.1-Unterstützung ist im Windows SDK enthalten.
Das folgende Diagramm enthält Beispiele für die Funktionsweise von WSPStartup in Verbindung mit verschiedenen versionen WS2_32.DLL und Windows Sockets Service Provider (SP).
| DLL |
SP |
wVersionRequested | wVersion | wHighVersion | Endergebnis |
|---|---|---|---|---|---|
| 1.1 | 1.1 | 1.1 | 1.1 | 1.1 | verwenden Sie 1.1 |
| 1.0 1.1 | 1.0 | 1.1 | 1.0 | 1.0 | verwenden Sie 1.0 |
| 1.0 | 1.0 1.1 | 1.0 | 1.0 | 1.1 | verwenden Sie 1.0 |
| 1.1 | 1.0 1.1 | 1.1 | 1.1 | 1.1 | verwenden Sie 1.1 |
| 1.1 | 1.0 | 1.1 | 1.0 | 1.0 | DLL schlägt fehl |
| 1.0 | 1.1 | 1.0 | --- | --- | WSAVERNOTSUPPORTED |
| 1.0 1.1 | 1.0 1.1 | 1.1 | 1.1 | 1.1 | verwenden Sie 1.1 |
| 1.0 1.1 2.0 | 1.1 | 2.0 | 1.1 | 1.1 | verwenden Sie 1.1 |
| 1.0 1.1 2.0 | 2.0 | 2.0 | 2.0 | 2.0 | verwenden Sie 2.0 |
| 1.0 1.1 2.0 2.1 2.2 | 2.2 | 2.2 | 2.2 | 2.2 | verwenden Sie 2.2 |
Das folgende Codefragment veranschaulicht, wie ein Windows Sockets SPI-Client, der nur Version 2 von Windows Sockets SPI unterstützt, einen WSPStartup-Aufruf ausgibt:
WORD wVersionRequested;
WSPDATA WSPData;
int err;
WSPUPCALLTABLE upcallTable =
{
/* initialize upcallTable with function pointers */
};
LPWSPPROC_TABLE lpProcTable =
{
/* allocate memory for the ProcTable */
};
wVersionRequested = MAKEWORD( 2, 2 );
err = WSPStartup( wVersionRequested, &WSPData, lpProtocolBuffer, upcallTable, lpProcTable );
if ( err != 0 ) {
/* Tell the user that we could not find a usable */
/* Windows Sockets service provider. */
return;
}
/* Confirm that the Windows Sockets service provider supports 2.2.*/
/* Note that if the service provider 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( WSPData.wVersion ) != 2 ||
HIBYTE( WSPData.wVersion ) != 2 ) {
/* Tell the user that we could not find a usable */
/* Windows Sockets service provider. */
LPWSPCleanup( );
return;
}
/* The Windows Sockets service provider is acceptable. Proceed. */
Dieses Codefragment veranschaulicht, wie ein Windows Sockets-Dienstanbieter, der nur Version 2.2 unterstützt, die WSPStartup-Aushandlung ausführt:
/* Make sure that the version requested is >= 2.2. */
/* The low byte is the major version and the high */
/* byte is the minor version. */
if ( (LOBYTE( wVersionRequested ) < 2) ||
((LOBYTE( wVersionRequested ) == 2) &&
(HIBYTE( wVersionRequested ) < 2))) {
return WSAVERNOTSUPPORTED;
}
/* Since we only support 2.2, set both wVersion and */
/* wHighVersion to 2.2. */
lpWSPData->wVersion = MAKEWORD( 2, 2 );
lpWSPData->wHighVersion = MAKEWORD( 2, 2 );
Sobald der Windows Sockets SPI-Client einen erfolgreichen WSPStartup-Aufruf ausgeführt hat, kann er nach Bedarf weitere Windows Sockets SPI-Aufrufe ausführen. Wenn er die Dienste des Windows Sockets-Dienstanbieters verwendet hat, muss der Client LPWSPCleanup aufrufen, damit der Windows Sockets-Dienstanbieter alle für den Client zugewiesenen Ressourcen freigeben kann.
Die WSPStartup-Funktion muss von jedem Clientprozess mindestens einmal aufgerufen werden und kann von der Winsock 2-DLL oder anderen Entitäten mehrmals aufgerufen werden. Für jeden erfolgreichen WSPStartup-Aufruf muss eine entsprechende LPWSPCleanup-Funktion aufgerufen werden. Der Dienstanbieter sollte eine Referenzanzahl pro Prozess beibehalten. Bei jedem WSPStartup-Aufruf kann der Aufrufer eine beliebige Versionsnummer angeben, die von der Dienstanbieter-DLL unterstützt wird.
Ein Dienstanbieter muss den Zeiger auf die Upcall-Dispatchtabelle des Clients speichern, die von der WSPStartup-Funktion prozessbezogen als UpcallTable-Parameter empfangen wird. Wenn ein bestimmter Prozess WSPStartup mehrmals aufruft, muss der Dienstanbieter nur den zuletzt bereitgestellten Upcall-Dispatchtabellenzeiger verwenden.
Ein Windows Sockets SPI-Client kann WSPStartup mehrmals aufrufen, wenn die WSPDATA-Strukturinformationen mehrmals abgerufen werden müssen. Bei jedem solchen Aufruf kann der Client eine beliebige Versionsnummer angeben, die vom Anbieter unterstützt wird.
Es muss ein LPWSPCleanup-Aufruf vorhanden sein, der jedem erfolgreichen WSPStartup-Aufruf entspricht, damit DLLs von Drittanbietern einen Windows Sockets-Anbieter verwenden können. Dies bedeutet beispielsweise, dass der entsprechende Aufruf von LPWSPCleanup dreimal erfolgen muss, wenn WSPStartup dreimal aufgerufen wird. Die ersten beiden Aufrufe von LPWSPCleanup führen nichts anderes aus, als einen internen Zähler zu dekrementieren. der letzte LPWSPCleanup-Aufruf führt alle erforderlichen Ressourcendeallocations durch.
Diese Funktion (und die meisten anderen Dienstanbieterfunktionen) kann in einem Thread aufgerufen werden, der als 16-Bit-Prozess gestartet wurde, wenn es sich beim Client um einen 16-Bit-Windows Sockets 1.1-Client handelt. Eine wichtige Einschränkung von 16-Bit-Prozessen ist, dass ein 16-Bit-Prozess keine Threads erstellen kann. Dies ist für Dienstanbieterimplementierungsanbieter von Bedeutung, die planen, einen internen Dienstthread als Teil der Implementierung zu verwenden.
Glücklicherweise gibt es in der Regel nur zwei Bereiche, in denen die Bedingungen für einen Dienstthread stark sind:
- Bei der Implementierung der überlappenden E/A-Vervollständigung.
- In der Implementierung von LPWSPEventSelect.
Auf beide Bereiche kann nur über neue Windows Sockets 2-Funktionen zugegriffen werden, die nur von 32-Bit-Prozessen aufgerufen werden können.
Ein Dienstthread kann sicher verwendet werden, wenn diese beiden Entwurfsregeln sorgfältig befolgt werden:
- Verwenden Sie einen Dienstthread nur für Funktionen, die für 16-Bit-Windows Sockets 1.1-Clients nicht verfügbar sind.
- Erstellen Sie den Dienstthread nur bei Bedarf.
Mehrere andere Vorsichtsmaßnahmen gelten für die Verwendung interner Dienstthreads. Erstens sind Threads in der Regel mit Leistungseinbußen zu betrafen. Verwenden Sie so wenige wie möglich, und vermeiden Sie Threadübergänge, wo immer möglich. Zweitens sollte Ihr Code immer nach Fehlern beim Erstellen von Threads suchen und ordnungsgemäß und informativ fehlschlagen (z. B. mit WSAEOPNOTSUPP), falls Sie bei einem Ausführungsereignis keine Ergebnisse in einem 16-Bit-Prozess erwartet haben, der einen Codepfad ausführt, für den Threads erforderlich sind.
Ein Mehrschichtdienstanbieter stellt eine Implementierung dieser Funktion bereit, ist aber auch ein Client dieser Funktion, wenn er WSPStartup aufruft, um die nächste Ebene in der Protokollkette zu initialisieren. Der Aufruf des WSPStartup der nächsten Ebene kann während der Ausführung des WSPStartup dieser Schicht erfolgen, oder er kann verzögert und bei Bedarf aufgerufen werden, z. B. wenn LPWSPSocket aufgerufen wird. In jedem Fall gelten einige besondere Überlegungen für den lpProtocolInfo-Parameter dieser Funktion, da er über die Ebenen der Protokollkette nach unten weitergegeben wird.
Der Mehrschichtanbieter durchsucht die ProtocolChain der Struktur, auf die von lpProtocolInfo verwiesen wird, um den eigenen Speicherort in der Kette (durch Die Suche nach der eigenen Katalogeintrags-ID der Ebene) und die Identität des nächsten Elements in der Kette zu ermitteln. Wenn das nächste Element eine andere Ebene ist, muss diese Ebene beim Aufruf des WSPStartup der nächsten Ebene eine lpProtocolInfo-Ebene übergeben, die auf dieselbe unveränderte WSAProtocol_Info Struktur mit den gleichen unveränderten Ketteninformationen verweist. Wenn die nächste Ebene jedoch das Basisprotokoll (d. h. das letzte Element in der Kette) ist, führt diese Ebene beim Aufrufen des WSPStartup des Basisanbieters eine Ersetzung durch. In diesem Fall sollte der lpProtocolInfo-Parameter auf die WSAPROTOCOL_INFO Struktur des Basisanbieters verweisen.
Ein wesentlicher Vorteil dieser Richtlinie ist, dass die Basisdienstanbieter keine Protokollketten kennen müssen.
Die gleiche Weitergaberichtlinie gilt beim Verteilen einer WSAPROTOCOL_INFO-Struktur über eine mehrschichtige Sequenz anderer Funktionen wie LPWSPAddressToString, LPWSPDuplicateSocket, LPWSPSocket oder LPWSPStringToAddress.
Anforderungen
| Anforderung | Wert |
|---|---|
| Unterstützte Mindestversion (Client) | Windows 2000 Professional [nur Desktop-Apps] |
| Unterstützte Mindestversion (Server) | Windows 2000 Server [nur Desktop-Apps] |
| Zielplattform | Windows |
| Kopfzeile | ws2spi.h |