Funzione WSCInstallProvider (ws2spi.h)
Sintassi
int WSCInstallProvider(
[in] LPGUID lpProviderId,
[in] const WCHAR *lpszProviderDllPath,
[in] const LPWSAPROTOCOL_INFOW lpProtocolInfoList,
[in] DWORD dwNumberOfEntries,
[out] LPINT lpErrno
);
Parametri
[in] lpProviderId
Puntatore a un identificatore univoco globale (GUID) per il provider.
[in] lpszProviderDllPath
Puntatore a una stringa Unicode contenente il percorso di caricamento della DLL del provider. Questa stringa osserva le normali regole per la risoluzione del percorso e può contenere stringhe di ambiente incorporate (ad esempio %SystemRoot%). Tali stringhe di ambiente vengono espanse quando la Ws2_32.dll deve successivamente caricare la DLL del provider per conto di un'applicazione. Dopo aver espanso tutte le stringhe di ambiente incorporate, la Ws2_32.dll passa la stringa risultante alla funzione LoadLibrary che carica il provider in memoria. Per altre informazioni, vedere LoadLibrary.
[in] lpProtocolInfoList
Puntatore a una matrice di strutture WSAProtocol_Info . Ogni struttura definisce un protocollo, una famiglia di indirizzi e un tipo socket supportato dal provider.
[in] dwNumberOfEntries
Numero di voci nella matrice lpProtocolInfoList .
[out] lpErrno
Puntatore al codice di errore se la funzione ha esito negativo.
Valore restituito
Se WSCInstallProvider 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 degli indirizzi utente. | |
| Uno o più argomenti non sono validi. | |
| Impossibile allocare memoria per i buffer. | |
| Si è verificato un errore non recuperabile. Questo errore viene restituito in diverse condizioni, tra cui quanto segue: il provider è già installato, l'utente non ha i privilegi amministrativi necessari per scrivere nel Registro Di sistema Winsock o si è verificato un errore durante la creazione o l'installazione di una voce di catalogo. | |
| Una chiamata di sistema che non deve mai avere esito negativo. | |
| Memoria insufficiente disponibile. Questo errore viene restituito quando è presente memoria insufficiente per allocare una nuova voce del catalogo. |
Commenti
WSCInstallProvider viene usato per installare un singolo provider di servizi di trasporto. Questa routine crea le informazioni di configurazione comuni di Windows Sockets 2 necessarie per il provider specificato. È applicabile ai protocolli di base, ai protocolli a livelli e alle catene di protocolli. Se viene installato un provider di servizi a livelli, è necessario usare WSCInstallProviderAndChains . WSCInstallProviderAndChains può installare un protocollo a livelli e una o più catene di protocolli con una singola chiamata a funzione. Per eseguire lo stesso lavoro usando WSCInstallProvider richiederebbe più chiamate di funzione.
Winsock 2 supporta protocolli a livelli. Un protocollo a 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 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 reciprocamente. Tale protocollo di sicurezza richiede in genere i servizi di un protocollo di trasporto affidabile sottostante, ad esempio TCP o SPX. Il termine protocollo di base fa riferimento a un protocollo come TCP o SPX che è in grado di eseguire comunicazioni dati con un endpoint remoto. Il termine protocollo a 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 livelli incatenati e ancorati da un protocollo di base. Un protocollo di base ha il membro ChainLen della struttura WSAProtocol_Info impostata su BASE_PROTOCOL definita come 1. Un protocollo a livelli ha il membro ChainLen della struttura WSAPROTOCOL_INFO impostata su LAYERED_PROTOCOL definita come zero. Una catena di protocolli ha il membro ChainLen della struttura WSAPROTOCOL_INFO impostata su maggiore di 1.
Il parametro lpProtocolInfoList contiene un elenco di voci del protocollo da installare. I chiamanti di WSCInstallProvider sono responsabili della configurazione delle voci di protocollo appropriate. Il parametro lpProtocolInfoList non deve essere NULL.
Al termine di questa chiamata, tutte le chiamate successive a WSAEnumProtocols o WSCEnumProtocols restituiranno le voci del protocollo appena create. Tenere presente che negli ambienti Windows, solo le istanze di Ws_32.dll create chiamando WSAStartup dopo il completamento corretto di WSCInstallProvider includeranno le nuove voci quando viene restituito WSAEnumProtocols e WSCEnumProtocols.
In caso di esito positivo, WSCInstallProvider tenterà di avvisare tutte le applicazioni interessate registrate per la notifica della modifica chiamando WSAProviderConfigChange.
La funzione WSCInstallProvider può essere chiamata solo da un utente connesso come membro del gruppo Administrators. Se WSCInstallProvider viene chiamato da un utente che non è membro del gruppo Administrators, la chiamata alla funzione avrà esito negativo e WSANO_RECOVERY viene restituita nel parametro lpErrno . Per i computer che eseguono Windows Vista o Windows Server 2008, questa funzione può anche non riuscire a causa del controllo dell'account utente. Se un'applicazione contenente 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 per richiedereAdministrator. Se l'applicazione in Windows Vista o Windows Server 2008 manca questo file manifesto, un utente ha eseguito l'accesso come membro del gruppo Administrators diverso dall'amministratore predefinito deve quindi eseguire l'applicazione in una shell avanzata come amministratore predefinito (amministratore RunAs) per questa funzione.
Qualsiasi installazione di file o configurazione specifica del provider di servizi deve essere eseguita dal chiamante.
Requisiti
| Client minimo supportato | Windows 2000 Professional [solo app desktop] |
| Server minimo supportato | Windows 2000 Server [solo app desktop] |
| Piattaforma di destinazione | Windows |
| Intestazione | ws2spi.h |
| Libreria | Ws2_32.lib |
| DLL | Ws2_32.dll |