Funzione WSCInstallProviderAndChains (ws2spi.h)
Nota
I provider di servizi su più livelli sono deprecati. A partire da Windows 8 e Windows Server 2012, usare Windows Filtering Platform. La funzione WSCInstallProviderAndChains installa il provider di trasporto a 32 bit specificato, nonché le catene di protocolli specifiche nel database di configurazione di sistema Winsock 2 in un computer a 32 bit. Questa funzione garantisce che le catene di protocolli vengano ordinate all'inizio delle informazioni di configurazione del provider di trasporto, assicurandosi che non sia necessaria una chiamata separata a WSCWriteProviderOrder .
Sintassi
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
);
Parametri
[in] lpProviderId
Puntatore a un identificatore univoco globale (GUID) specifico del provider.
[in] lpszProviderDllPath
Puntatore a una stringa Unicode contenente il percorso di caricamento della DLL del provider. Questa stringa osserva le regole consuete per la risoluzione del percorso e può contenere stringhe di ambiente incorporate (%SystemRoot%, ad esempio). Tali stringhe di ambiente vengono espanse ogni volta cheWs2_32.dll successivamente carica la DLL del provider per conto di un'applicazione. Dopo aver espanso tutte le stringhe di ambiente incorporate, Ws2_32.dll passa la stringa risultante nella funzione LoadLibrary per caricare il provider in memoria. Per altre informazioni, vedere LoadLibrary.
[in] lpszLspName
Puntatore a una stringa Unicode contenente il nome del provider di socket.
[in] dwServiceFlags
Flag del servizio per il tipo di voce di catalogo "fittizia" da creare.
Una voce fittizia è una struttura WSAProtocol_Info con il membro ChainLen impostato su 0. La voce del catalogo LSP effettiva farà riferimento all'ID di questa voce fittizia nel membro ProtocolChain .
I flag possibili che è possibile impostare per questo parametro sono i seguenti:
[in] lpProtocolInfoList
Puntatore a una matrice di strutture WSAProtocol_Info . Ogni struttura definisce un protocollo, una famiglia di indirizzi e un tipo di socket supportati dal provider. I membri della struttura WSAPROTOCOL_INFO esaminati sono iProtocol, iAddressFamily e iSocketType.
[in] dwNumberOfEntries
Numero di voci nella matrice lpProtocolInfoList .
[out, optional] lpdwCatalogEntryId
Riceve un puntatore alla voce "fittizia" appena installata per il provider di trasporto nel database di configurazione di sistema Winsock 2. Questo ID viene usato per installare le voci del catalogo per il provider di servizi di configurazione locale.
[out] lpErrno
Puntatore che riceve un codice di errore generato dalla chiamata se la funzione ha esito negativo.
Valore restituito
Se
WSCInstallProviderAndChains ha esito positivo, restituisce zero. In caso contrario, restituisce SOCKET_ERROR e viene restituito un codice di errore specifico nel parametro lpErrno .
| Codice di errore | Significato |
|---|---|
| Uno o più argomenti non si trovano in una parte valida dello spazio indirizzi utente. | |
| Uno o più argomenti non sono validi. Questo errore viene restituito per le condizioni seguenti: il parametro lpProviderId è **NULL**, il parametro lpszProviderDllPath non è valido o la lunghezza del percorso è troppo grande (**MAX_PATH** è stato superato), il parametro lpszLspName non è valido o la lunghezza del nome è troppo grande (**WSAPROTOCOL_LEN** viene superata), lpProtocolInfoList è impostato su un valore non NULL** e il parametro dwNumberOfEntries il parametro è zero, un ID provider duplicato o il nome del provider di servizi a più livelli esiste già nel catalogo oppure non è possibile trovare una corrispondenza per il protocollo, la famiglia di indirizzi e il tipo di socket specificati. | |
| È già in corso un'installazione del provider. | |
| Il provider manca la funzionalità necessaria. | |
| La memoria non può essere allocata per i buffer. | |
| Si è verificato un errore irreversibile. Questo errore viene restituito in diverse condizioni, tra cui: il provider è già installato, il parametro lpProtocolInfoList è stato **NULL** e non è stato trovato alcun provider di base, è stata raggiunta la lunghezza massima della catena di protocolli (**MAX_PROTOCOL_CHAIN**), l'utente non dispone dei privilegi amministrativi necessari per scrivere nel Registro di sistema Winsock o si è verificato un errore durante la creazione o l'installazione di una voce del catalogo. | |
| Chiamata di sistema che non dovrebbe mai avere esito negativo. |
Commenti
WSCInstallProviderAndChains è una versione avanzata della funzione WSCInstallProvider di base usata per installare un singolo provider di servizi di trasporto. Se è in corso l'installazione di un provider di servizi a più livelli, è necessario usare WSCInstallProviderAndChains . WSCInstallProviderAndChains può installare un protocollo a più livelli e una o più catene di protocolli con una singola chiamata di funzione. Per eseguire lo stesso lavoro usando WSCInstallProvider , sono necessarie più chiamate di funzione.
Winsock 2 supporta protocolli a più livelli. Un protocollo a più livelli è uno che implementa solo funzioni di comunicazione di livello superiore, mentre si basa su uno stack di trasporto sottostante per lo scambio effettivo di dati con un endpoint remoto. Un esempio di protocollo a più livelli è un livello di sicurezza che aggiunge un protocollo al processo di creazione della connessione per eseguire l'autenticazione e stabilire uno schema di crittografia concordato a vicenda. Un protocollo di sicurezza di questo tipo richiede in genere i servizi di un protocollo di trasporto affidabile sottostante, ad esempio TCP o SPX. Il termine protocollo di base si riferisce a un protocollo, ad esempio TCP o SPX, in grado di eseguire comunicazioni di dati con un endpoint remoto. Il termine protocollo a più livelli viene usato per descrivere un protocollo che non può essere autonomo. Una catena di protocolli verrebbe quindi definita come uno o più protocolli a più livelli collegati e ancorati da un protocollo di base. Un protocollo di base ha il membro ChainLen della struttura WSAProtocol_Info impostata su BASE_PROTOCOL che è definito come 1. Un protocollo a più livelli ha il membro ChainLen della struttura WSAPROTOCOL_INFO impostata su LAYERED_PROTOCOL che è definito come zero. Una catena di protocolli ha il membro ChainLen della struttura WSAPROTOCOL_INFO impostata su maggiore di 1.
Se lpProtocolInfoList è impostato su NULL, questa funzione crea catene di protocolli in cui il provider viene sovrapposto al protocollo di base per ogni tipo di protocollo univoco, come definito dalla famiglia di indirizzi, dal tipo di socket e dal protocollo. In questo modo viene eliminata la creazione di eventuali voci di provider duplicate inaccessibili.
Se lpProtocolInfoList è impostato su un valore non NULL , questa funzione crea catene di protocolli ottenendo la voce più in alto nelle informazioni di configurazione corrispondenti alla famiglia di indirizzi, al tipo di socket e al protocollo di ogni elemento nella matrice specificata. Anche in questo caso, vengono considerati solo la famiglia di indirizzi, il tipo di socket e il protocollo; tutti gli altri membri e duplicati vengono ignorati.
Al termine di questa chiamata, tutte le chiamate successive a WSAEnumProtocols o WSCEnumProtocols restituiranno le voci della catena di protocolli appena create. Tenere presente che negli ambienti Windows solo le istanze di Ws_32.dll create chiamando WSAStartup dopo il completamento corretto di WSCInstallProviderAndChains includeranno le nuove voci quando WSAEnumProtocols e WSCEnumProtocols restituisce .
In caso di esito positivo, WSCInstallProviderAndChains tenterà di avvisare tutte le applicazioni interessate registrate per la notifica della modifica chiamando WSAProviderConfigChange.
La funzione WSCInstallProviderAndChains può essere chiamata solo da un utente connesso come membro del gruppo Administrators. Se WSCInstallProviderAndChains viene chiamato da un utente che non è membro del gruppo Administrators, la chiamata di funzione avrà esito negativo e WSANO_RECOVERY viene restituito nel parametro lpErrno . Per i computer che eseguono Windows Vista o Windows Server 2008, questa funzione può avere esito negativo anche a causa del controllo dell'account utente. Se un'applicazione che contiene questa funzione viene eseguita da un utente connesso come membro del gruppo Administrators diverso dall'amministratore predefinito, questa chiamata avrà esito negativo a meno che l'applicazione non sia stata contrassegnata nel file manifesto con un set requestedExecutionLevel impostato su requireAdministrator. Se l'applicazione in Windows Vista o Windows Server 2008 non dispone di questo file manifesto, un utente connesso come membro del gruppo Administrators diverso dall'amministratore predefinito deve quindi eseguire l'applicazione in una shell avanzata come amministratore predefinito (amministratore RunAs) affinché questa funzione abbia esito positivo.
Qualsiasi installazione di file o configurazione specifica del provider deve essere eseguita dall'applicazione chiamante.
Requisiti
| Requisito | Valore |
|---|---|
| Client minimo supportato | Windows Vista [solo app desktop] |
| Server minimo supportato | Windows Server 2008 [solo app desktop] |
| Piattaforma di destinazione | Windows |
| Intestazione | ws2spi.h |
| Libreria | Ws2_32.lib |
| DLL | Ws2_32.dll |
Vedi anche
Configurazione e installazione del trasporto