WSCInstallProviderAndChains-Funktion (ws2spi.h)

Artikel
03/04/2024

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:

Wert	Bedeutung
XP1_IFS_HANDLES	Der Katalogeintrag ist für einen IFS-LSP (Installable File System) vorgesehen, der IFS-spezifische Sockethandles zurückgibt. Diese Handles werden direkt an die aufrufende Anwendung zurückgegeben. Ein IFS-LSP kann den Abschluss von Winsock-Aufrufen nicht abfangen und muss nicht alle Winsock-Funktionen implementiert oder verfügbar haben.

[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
WSAEFAULT	Mindestens eines der Argumente befindet sich nicht in einem gültigen Teil des Benutzeradressraums.
WSAEINVAL	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.
WSAEINPROGRESS	Eine Anbieterinstallation wird bereits ausgeführt.
WSAEINVALIDPROCTABLE	Dem Anbieter fehlen die erforderlichen Funktionen.
WSAENOBUFS	Speicher kann nicht für Puffer zugeordnet werden.
WSANO_RECOVERY	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.
WSASYSCALLFAILURE	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.

Hinweis Die WSAEnumProtocols-Funktion listet keinen mehrstufigen Protokolleintrag auf, während WSCEnumProtocols dies tut.

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