Funzione RasSetCredentialsA (ras.h)

Articolo
08/25/2023

La funzione RasSetCredentials imposta le credenziali utente associate a una voce di telefono 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 PBK (Phone Book). Se questo parametro è NULL, la funzione usa il file di rubrica telefonico predefinito corrente. Il file di rubrica telefonico predefinito è quello selezionato dall'utente nella finestra di proprietà 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 sizeof(RASCREDENTIALS) 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 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 da Codici di errore routing e accesso remoto o WinError.h.

Valore	Significato
ERROR_CANNOT_OPEN_PHONEBOOK	Impossibile trovare la rubrica telefonica specificata.
ERROR_INVALID_PARAMETER	Il parametro lpCredentials era NULL o la voce specificata non esiste nella rubrica telefonica.
ERROR_ACCESS_DENIED	Si è verificata una delle seguenti condizioni: 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-user. L'utente non dispone dei privilegi corretti per impostare chiavi o credenziali pre-condivise per tutti gli utenti in caso di connectoid all-user. Solo gli amministratori possono completare queste attività.

Commenti

La funzione RasSetCredentials imposta le credenziali utente associate a una voce di telefono 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 alla funzione RasSetCredentials o RasSetEntryDialParams per la voce della rubrica telefonica.

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

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

Per impostare le credenziali predefinite per una connessione all-utente, impostare il flag 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 a tutti gli utenti, se l'applicazione chiamante specifica un valore non NULL per il parametro phone-book, lpszPhonebook, il file della rubrica telefonica deve trovarsi nella directory della 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 dati dell'applicazione all-users. Aggiungere la stringa seguente a questo percorso:

Microsoft\Network\Connections\Pbk

Il percorso combinato è il percorso corretto per il file della rubrica telefonica.

Nota Se si specifica un valore non NULL per il parametro lpszPhonebook , potrebbe non essere supportato nelle versioni successive del sistema operativo Windows.

Per impostare una chiave pre-condivisa, usare il flag RASCM_PreSharedKey in 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 di codifica neutrale con il codice che non è neutrale dalla codifica può causare errori di corrispondenza che causano errori di compilazione o runtime. Per altre informazioni, vedere Convenzioni per i prototipi di funzione.

Requisiti


Client minimo supportato	Windows 2000 Professional [solo app desktop]
Server minimo supportato	Windows 2000 Server [solo app desktop]
Piattaforma di destinazione	Windows
Intestazione	ras.h
Libreria	Rasapi32.lib
DLL	Rasapi32.dll