WSCInstallProviderAndChains-Funktion (ws2spi.h)
Hinweis
Mehrschichtige Dienstanbieter sind veraltet. Verwenden Sie ab Windows 8 und Windows Server 2012 die Windows-Filterplattform. Die WSCInstallProviderAndChains-Funktion installiert den angegebenen 32-Bit-Transportanbieter sowie seine spezifischen Protokollketten in der Winsock 2-Systemkonfigurationsdatenbank auf einem 32-Bit-Computer. Diese Funktion stellt sicher, dass die Protokollketten am Anfang der Konfigurationsinformationen des Transportanbieters sortiert werden, sodass kein separater Aufruf von WSCWriteProviderOrder erforderlich ist.
Syntax
int WSCInstallProviderAndChains(
[in] LPGUID lpProviderId,
[in] const LPWSTR lpszProviderDllPath,
[in] const LPWSTR lpszLspName,
[in] DWORD dwServiceFlags,
[in] LPWSAPROTOCOL_INFOW lpProtocolInfoList,
[in] DWORD dwNumberOfEntries,
[out, optional] LPDWORD lpdwCatalogEntryId,
[out] LPINT lpErrno
);
Parameter
[in] lpProviderId
Ein Zeiger auf einen anbieterspezifischen, global eindeutigen Bezeichner (GUID).
[in] lpszProviderDllPath
Ein Zeiger auf eine Unicode-Zeichenfolge, die den Ladepfad zur DLL des Anbieters enthält. Diese Zeichenfolge beachtet die üblichen Regeln für die Pfadauflösung und kann eingebettete Umgebungszeichenfolgen enthalten (z. B. %SystemRoot%). Solche Umgebungszeichenfolgen werden immer dann erweitert , wennWs2_32.dll anschließend die Anbieter-DLL im Namen einer Anwendung lädt. Nachdem eingebettete Umgebungszeichenfolgen erweitert wurden, übergibtWs2_32.dll die resultierende Zeichenfolge an die LoadLibrary-Funktion , um den Anbieter in den Arbeitsspeicher zu laden. Weitere Informationen finden Sie unter LoadLibrary.
[in] lpszLspName
Ein Zeiger auf eine Unicode-Zeichenfolge, die den Namen des Socketanbieters enthält.
[in] dwServiceFlags
Die Dienstflags für den Typ des zu erstellenden Katalogeintrags "dummy".
Ein Dummyeintrag ist eine WSAProtocol_Info-Struktur , bei der das ChainLen-Element auf 0 festgelegt ist. Der tatsächliche LSP-Katalogeintrag verweist auf die ID dieses Dummyeintrags in seinem ProtocolChain-Member .
Die möglichen Flags, die für diesen Parameter festgelegt werden können, sind wie folgt:
[in] lpProtocolInfoList
Ein Zeiger auf ein Array von WSAProtocol_Info Strukturen. Jede Struktur definiert ein Protokoll, eine Adressfamilie und einen Sockettyp, der vom Anbieter unterstützt wird. Die Elemente der WSAPROTOCOL_INFO-Struktur , die untersucht werden, sind iProtocol, iAddressFamily und iSocketType.
[in] dwNumberOfEntries
Die Anzahl der Einträge im LpProtocolInfoList-Array .
[out, optional] lpdwCatalogEntryId
Empfängt einen Zeiger auf den neu installierten "Dummy"-Eintrag für den Transportanbieter in der Winsock 2-Systemkonfigurationsdatenbank. Diese ID wird verwendet, um die Katalogeinträge für den LSP zu installieren.
[out] lpErrno
Ein Zeiger, der einen vom Aufruf generierten Fehlercode empfängt, wenn die Funktion fehlschlägt.
Rückgabewert
Wenn
WSCInstallProviderAndChains ist erfolgreich, gibt null zurück. Andernfalls wird SOCKET_ERROR zurückgegeben, und im lpErrno-Parameter wird ein bestimmter Fehlercode zurückgegeben.
| Fehlercode | Bedeutung |
|---|---|
| Mindestens eines der Argumente befindet sich nicht in einem gültigen Teil des Benutzeradressraums. | |
| Mindestens ein Argument ist ungültig. Dieser Fehler wird für die folgenden Bedingungen zurückgegeben: Der lpProviderId-Parameter ist **NULL**, der lpszProviderDllPath-Parameter ungültig oder die Pfadlänge ist zu groß (**MAX_PATH** wurde überschritten), der lpszLspName-Parameter ungültig oder die Namenslänge ist zu groß (**WSAPROTOCOL_LEN** wird überschritten), die lpProtocolInfoList ist auf ein nicht-**NULL** und die dwNumberOfEntries festgelegt. der Parameter ist null, eine doppelte Anbieter-ID oder der Name des mehrstufigen Dienstanbieters ist bereits im Katalog vorhanden, oder es wurde keine Übereinstimmung für das angegebene Protokoll, die angegebene Adressfamilie und den angegebenen Sockettyp gefunden. | |
| Eine Anbieterinstallation wird bereits ausgeführt. | |
| Dem Anbieter fehlen die erforderlichen Funktionen. | |
| Speicher kann nicht für Puffer zugeordnet werden. | |
| Ein nicht behebbarer Fehler ist aufgetreten. Dieser Fehler wird unter verschiedenen Bedingungen zurückgegeben, einschließlich der folgenden: Der Anbieter ist bereits installiert, der parameter lpProtocolInfoList war **NULL**, und es wurde kein Basisanbieter gefunden, die maximale Protokollkettenlänge (**MAX_PROTOCOL_CHAIN**) wurde erreicht, der Benutzer verfügt nicht über die Administratorrechte, die zum Schreiben in die Winsock-Registrierung erforderlich sind, oder beim Erstellen oder Installieren eines Katalogeintrags ist ein Fehler aufgetreten. | |
| Ein Systemaufruf, der nie fehlschlagen sollte, ist fehlgeschlagen. |
Hinweise
WSCInstallProviderAndChains ist eine erweiterte Version der grundlegenden WSCInstallProvider-Funktion , die zum Installieren eines einzelnen Transportdienstanbieters verwendet wird. Wenn ein Mehrschichtdienstanbieter installiert wird, sollte WSCInstallProviderAndChains verwendet werden. WSCInstallProviderAndChains kann ein mehrstufiges Protokoll und eine oder mehrere Protokollketten mit einem einzelnen Funktionsaufruf installieren. Um die gleiche Arbeit mit WSCInstallProvider auszuführen, wären mehrere Funktionsaufrufe erforderlich.
Winsock 2 bietet mehrstufige Protokolle. Ein mehrstufiges Protokoll ist ein Protokoll, das nur Kommunikationsfunktionen auf höherer Ebene implementiert, während ein zugrunde liegender Transportstapel für den tatsächlichen Austausch von Daten mit einem Remoteendpunkt verwendet wird. Ein Beispiel für ein mehrschichtiges Protokoll wäre eine Sicherheitsebene, die dem Verbindungsaufbauprozess ein Protokoll hinzufügt, um die Authentifizierung durchzuführen und ein gemeinsam vereinbartes Verschlüsselungsschema einzurichten. Ein solches Sicherheitsprotokoll erfordert im Allgemeinen die Dienste eines zugrunde liegenden zuverlässigen Transportprotokolls wie TCP oder SPX. Der Begriff Basisprotokoll bezieht sich auf ein Protokoll wie TCP oder SPX, das die Datenkommunikation mit einem Remoteendpunkt durchführen kann. Der Begriff Mehrschichtprotokoll wird verwendet, um ein Protokoll zu beschreiben, das nicht allein stehen kann. Eine Protokollkette würde dann als ein oder mehrere mehrstufige Protokolle definiert, die zusammengekettet und durch ein Basisprotokoll verankert sind. Bei einem Basisprotokoll ist der ChainLen-Member der WSAProtocol_Info-Struktur auf BASE_PROTOCOL festgelegt, der als 1 definiert ist. Bei einem mehrstufigen Protokoll ist der ChainLen-Member der WSAPROTOCOL_INFO-Struktur auf LAYERED_PROTOCOL festgelegt, der als null definiert ist. In einer Protokollkette ist der ChainLen-Member der WSAPROTOCOL_INFO-Struktur auf größer als 1 festgelegt.
Wenn lpProtocolInfoList auf NULL festgelegt ist, erstellt diese Funktion Protokollketten, bei denen der Anbieter über das Basisprotokoll für jeden eindeutigen Protokolltyp verteilt wird, wie durch die Adressfamilie, den Sockettyp und das Protokoll definiert. Dadurch wird das Erstellen von nicht zugänglichen doppelten Anbietereinträgen vermieden.
Wenn lpProtocolInfoList auf einen Wert ungleich NULL festgelegt ist, erstellt diese Funktion Protokollketten, indem der oberste Eintrag in den Konfigurationsinformationen abgerufen wird, der der Adressfamilie, dem Sockettyp und dem Protokoll von jedem Element im bereitgestellten Array entspricht. Auch hier werden nur die Adressfamilie, der Sockettyp und das Protokoll berücksichtigt. alle anderen Member und Duplikate werden ignoriert.
Nach erfolgreichem Abschluss dieses Aufrufs geben alle nachfolgenden Aufrufe von WSAEnumProtocols oder WSCEnumProtocols die neu erstellten Protokollketteneinträge zurück. Beachten Sie, dass in Windows-Umgebungen nur Instanzen von Ws_32.dll, die nach erfolgreichem Abschluss von WSCInstallProviderAndChains durch Aufrufen von WSAStartup erstellt wurden, die neuen Einträge enthalten, wenn WSAEnumProtocols und WSCEnumProtocols zurückgegeben werden.
Bei Erfolg versucht WSCInstallProviderAndChains, alle interessierten Anwendungen, die sich für die Benachrichtigung über die Änderung registriert haben, zu benachrichtigen, indem WSAProviderConfigChange aufgerufen wird.
Die WSCInstallProviderAndChains-Funktion kann nur von einem Benutzer aufgerufen werden, der als Mitglied der Gruppe Administratoren angemeldet ist. Wenn WSCInstallProviderAndChains von einem Benutzer aufgerufen wird, der kein Mitglied der Gruppe Administratoren ist, schlägt der Funktionsaufruf fehl, und WSANO_RECOVERY wird im lpErrno-Parameter zurückgegeben. Bei Computern, auf denen Windows Vista oder Windows Server 2008 ausgeführt wird, kann diese Funktion auch aufgrund der Benutzerkontensteuerung (UAC) fehlschlagen. Wenn eine Anwendung, die diese Funktion enthält, von einem Benutzer ausgeführt wird, der als Mitglied der Gruppe Administratoren angemeldet ist, die nicht der integrierten Administratorgruppe angehört, schlägt dieser Aufruf fehl, es sei denn, die Anwendung wurde in der Manifestdatei mit einem requestedExecutionLevel gekennzeichnet, der auf requireAdministrator festgelegt ist. Wenn in der Anwendung unter Windows Vista oder Windows Server 2008 diese Manifestdatei nicht vorhanden ist, muss ein Benutzer, der sich als Mitglied der Gruppe "Administratoren" angemeldet hat und nicht der integrierte Administrator die Anwendung in einer erweiterten Shell als integrierter Administrator (RunAs-Administrator) ausführen, damit diese Funktion erfolgreich ist.
Jede Dateiinstallation oder anbieterspezifische Konfiguration muss von der aufrufenden Anwendung ausgeführt werden.
Anforderungen
| Anforderung | Wert |
|---|---|
| Unterstützte Mindestversion (Client) | Windows Vista [nur Desktop-Apps] |
| Unterstützte Mindestversion (Server) | Windows Server 2008 [nur Desktop-Apps] |
| Zielplattform | Windows |
| Kopfzeile | ws2spi.h |
| Bibliothek | Ws2_32.lib |
| DLL | Ws2_32.dll |