Funzione RasSetCredentialsA (ras.h)

Articolo
11/20/2024

La funzione RasSetCredentials imposta le credenziali utente associate a una voce di rubrica RAS specificata.

Sintassi

DWORD RasSetCredentialsA(
  [in] LPCSTR            unnamedParam1,
  [in] LPCSTR            unnamedParam2,
  [in] LPRASCREDENTIALSA unnamedParam3,
  [in] BOOL              unnamedParam4
);

Parametri

[in] unnamedParam1

Puntatore a una stringa con terminazione Null che specifica il percorso completo e il nome file di un file con rubrica telefonica (PBK). Se questo parametro è NULL, la funzione usa il file predefinito corrente della rubrica telefonica. Il file predefinito della rubrica telefonica è quello selezionato dall'utente nella finestra di dialogo Preferenze utente della finestra di dialogo Rete remota.

[in] unnamedParam2

Puntatore a una stringa con terminazione Null che specifica il nome di una voce della rubrica telefonica.

[in] unnamedParam3

Puntatore a una struttura RASCREDENTIALS che specifica le credenziali utente da impostare per la voce della rubrica telefonica specificata. Prima di chiamare RasSetCredentials, impostare il membro dwSize della struttura su e impostare il membro dwMask per indicare le informazioni sulle credenziali da impostare.

[in] unnamedParam4

Valore che specifica se RasSetCredentials cancella le credenziali esistenti impostandole sulla stringa vuota "". Se questo flag è TRUE, il membro dwMask della struttura di RASCREDENTIALS indica le credenziali impostate dalla funzione sulla stringa vuota. Se questo flag è FALSE, la funzione imposta le credenziali indicate in base al contenuto dei membri RASCREDENTIALS corrispondenti.

Valore restituito

Se la funzione ha esito positivo, il valore restituito è ERROR_SUCCESS.

Se la funzione ha esito negativo, il valore restituito è uno dei codici di errore seguenti o un valore di Routing e codici di errore di accesso remoto o WinError.h.

Valore	Significato
ERROR_CANNOT_OPEN_PHONEBOOK	Impossibile trovare la rubrica specificata.
ERROR_INVALID_PARAMETER	Il parametro lpCredentials è stato NULLoppure la voce specificata non esiste nella rubrica telefonica.
ERROR_ACCESS_DENIED	Si è verificata una delle condizioni seguenti: L'applicazione chiamante ha tentato di impostare le credenziali predefinite per una connessione per utente. Le credenziali predefinite possono essere impostate solo per una connessione all-utente. L'utente non dispone dei privilegi corretti per impostare chiavi o credenziali precondivie per tutti gli utenti in caso di connectoid all-user. Solo gli amministratori possono completare queste attività.

Osservazioni

La funzione RasSetCredentials imposta le credenziali utente associate a una voce di rubrica RAS specificata. Le credenziali archiviate con una voce della rubrica telefonica sono le credenziali dell'ultimo utente per connettersi correttamente usando la voce della rubrica telefonica specificata o le credenziali specificate successivamente in una chiamata al RasSetCredentials o funzione rasSetEntryDialParams per la voce della rubrica telefonica.

La funzione RasSetCredentials è il modo preferito per archiviare in modo sicuro le credenziali con una voce della rubrica telefonica. RasSetCredentials sostituisce la funzione RasSetEntryDialParams, che potrebbe non essere supportata nelle versioni future del sistema operativo Windows.

Un handle di password è "****************" (16 asterischi). Se si chiama RasGetCredentials e si riceve 16 *s di nuovo nel campo della password, si dispone di una password archiviata e, per motivi di sicurezza, non verrà restituito all'utente in testo normale. Se il membro szPassword della struttura RASCREDENTIALS contiene l'handle di password (16 *s) restituito da RasGetCredentials o RasGetEntryDialParams, la chiamata successiva a RasSetCredentials non modificherà la password salvata.

Per impostare le credenziali predefinite per una connessione all-utente, impostare il flag di RASCM_DefaultCreds nel membro dwMask della struttura RASCREDENTIALS a cui punta il parametro lpCredentials . Se si tenta di impostare le credenziali predefinite per una connessione per utente, RasSetCredentials restituisce ERROR_ACCESS_DENIED.

Quando si impostano le credenziali per una connessione all-users, se l'applicazione chiamante specifica un valore non NULL per il parametro phone-book, lpszPhonebook, il file della rubrica telefonica deve trovarsi nella directory rubrica telefonica sotto il percorso dei dati dell'applicazione all-users. Per ottenere la posizione corretta per il file della rubrica telefonica, chiamare prima SHGetFolderPath con un valore CSIDL di CSIDL_COMMON_APPDATA. SHGetFolderPath restituisce il percorso dei dati dell'applicazione all-users. Aggiungere la stringa seguente a questo percorso:

Microsoft\Network\Connections\Pbk

Il percorso combinato è la posizione corretta per il file della rubrica telefonica.

Nota La specifica di un valore non NULL per il parametro lpszPhonebook potrebbe non essere supportata nelle versioni successive del sistema operativo Windows.

Per impostare una chiave precondi shared, usare il flag RASCM_PreSharedKey nel RASCREDENTIALS.campo dwMask.

Nota

L'intestazione ras.h definisce RasSetCredentials come alias che seleziona automaticamente la versione ANSI o Unicode di questa funzione in base alla definizione della costante del preprocessore UNICODE. La combinazione dell'utilizzo dell'alias indipendente dalla codifica con il codice non indipendente dalla codifica può causare mancate corrispondenze che generano errori di compilazione o di runtime. Per altre informazioni, vedere convenzioni di per i prototipi di funzioni.

Fabbisogno

Requisito	Valore
client minimo supportato	Windows 2000 Professional [solo app desktop]
server minimo supportato	Windows 2000 Server [solo app desktop]
piattaforma di destinazione	Finestre
intestazione	ras.h
libreria	Rasapi32.lib
dll	Rasapi32.dll