RasGetCredentialsA, fonction (ras.h)
La fonction RasGetCredentials récupère les informations d’identification de l’utilisateur associées à une entrée de livre téléphonique RAS spécifiée.
Syntaxe
DWORD RasGetCredentialsA(
[in] LPCSTR unnamedParam1,
[in] LPCSTR unnamedParam2,
[in, out] LPRASCREDENTIALSA unnamedParam3
);
Paramètres
[in] unnamedParam1
Pointeur vers une chaîne null-terminated qui spécifie le chemin d’accès complet et le nom de fichier d’un fichier PBK (Phone-Book). Si ce paramètre est NULL, la fonction utilise le fichier de livre téléphonique par défaut actuel. Le fichier de carnet téléphonique par défaut est celui sélectionné par l’utilisateur dans la feuille de propriétés Préférences utilisateur de la boîte de dialogue Mise en réseau rendez-vous.
[in] unnamedParam2
Pointeur vers une chaîne null-terminated qui spécifie le nom d’une entrée phone-book.
[in, out] unnamedParam3
Pointeur vers la structure RASCREDENTIALS qui, en sortie, reçoit les informations d’identification de l’utilisateur associées à l’entrée de carnet de téléphone spécifiée.
Lors de l’entrée, définissez le membre dwSize de la structure sur sizeof(RASCREDENTIALS), puis définissez le membre dwMask pour indiquer les informations d’identification à récupérer. Lorsque la fonction est retournée, dwMask indique les membres qui ont été récupérés avec succès.
Valeur de retour
Si la fonction réussit, la valeur de retour est ERROR_SUCCESS.
Si la fonction échoue, la valeur de retour est l’un des codes d’erreur suivants ou une valeur de Codes d’erreur d’acheminement et d’accès à distance ou Winerror.h.
| Valeur | Signification |
|---|---|
|
Le carnet de téléphone spécifié est introuvable. |
|
L’entrée spécifiée n’existe pas dans le carnet de téléphones. |
|
Le paramètre |
|
Le membre |
Remarques
La fonction RasGetCredentials récupère les informations d’identification du dernier utilisateur afin de se connecter à l’aide de l’entrée de carnet téléphonique spécifiée, ou les informations d’identification spécifiées par la suite dans un appel à la fonction RasSetCredentials pour l’entrée de carnet téléphonique.
Cette fonction est le moyen préféré de récupérer en toute sécurité les informations d’identification associées à une entrée de carnet de téléphone RAS. RasGetCredentials remplace la fonction RasGetEntryDialParams, qui peut ne pas être prise en charge dans les futures versions de Windows.
RasGetCredentials ne retourne pas le mot de passe réel. Au lieu de cela, le szPassword membre de la structure RASCREDENTIALS contient un handle pour le mot de passe enregistré. Remplacez ce handle pour le mot de passe enregistré dans les appels suivants à RasSetCredentials et rasDial. Lorsqu’elle est présentée avec ce handle, RasDial récupère et utilise le mot de passe enregistré. La valeur de ce handle peut changer dans les futures versions du système d’exploitation ; ne développez pas de code qui dépend du contenu ou du format de cette valeur.
Le membre dwMask de RASCREDENTIAL S contient l’indicateur RASCM_Password si le système a enregistré un mot de passe pour l’entrée spécifiée. Si le système n’a pas de mot de passe enregistré pour cette entrée, dwMask ne contient pas de RASCM_Password.
Windows 2000/NT : Cette fonctionnalité n’est pas prise en charge.
Si l'dwMask de la structure RASCREDENTIALS contient l’indicateur RASCM_DefaultCreds, les informations d’identification retournées sont les informations d’identification par défaut pour une connexion à tous les utilisateurs.
Pour récupérer une clé pré-partagée, utilisez l’indicateur RASCM_PreSharedKey dans le champ RASCREDENTIALS.dwMask.
Windows 2000/NT : Cette fonctionnalité n’est pas prise en charge.
L’exemple de code suivant crée l’entrée de carnet de téléphone « RasEntryName », définit ses informations d’identification à l’aide de RasSetCredentials, puis récupère ces informations d’identification à l’aide de RasGetCredentials.
#include <windows.h>
#include "ras.h"
#include <stdio.h>
#include <tchar.h>
#include "strsafe.h"
#define PHONE_NUMBER_LENGTH 7
#define DEVICE_NAME_LENGTH 5
#define DEVICE_TYPE_LENGTH 5
#define DOMAIN_NAME_LENGTH 9
#define USER_NAME_LENGTH 11
DWORD __cdecl wmain(){
DWORD dwRet = ERROR_SUCCESS;
LPTSTR lpszEntry = L"RasEntryName";
LPTSTR lpszPhoneNumber = L"5555555";
LPTSTR lpszDeviceName = L"Modem";
LPTSTR lpszDeviceType = RASDT_Modem;
LPTSTR lpszDomainName = L"RASDomain";
LPTSTR lpszUserName = L"RASUserName";
/***********************************************************************************************/
// Create a new phone book entry
/***********************************************************************************************/
// Allocate heap memory for the RASENTRY structure
LPRASENTRY lpentry = (LPRASENTRY)HeapAlloc(GetProcessHeap(), HEAP_ZERO_MEMORY, sizeof(RASENTRY));
if (lpentry == NULL){
wprintf(L"HeapAlloc failed!\n");
return 0;
}
// The RASENTRY->dwSize member has to be initialized or the RRAS RasValidateEntryName() and
// RasSetEntryProperties APIs will fail below.
lpentry->dwSize = sizeof(RASENTRY);
lpentry->dwFramingProtocol = RASFP_Ppp;
lpentry->dwfOptions = 0;
lpentry->dwType = RASFP_Ppp;
dwRet |= StringCchCopyN(lpentry->szLocalPhoneNumber, RAS_MaxPhoneNumber, lpszPhoneNumber, PHONE_NUMBER_LENGTH);
dwRet |= StringCchCopyN(lpentry->szDeviceName, RAS_MaxDeviceName, lpszDeviceName, DEVICE_NAME_LENGTH);
dwRet |= StringCchCopyN(lpentry->szDeviceType, RAS_MaxDeviceType, lpszDeviceType, DEVICE_TYPE_LENGTH);
if (dwRet != ERROR_SUCCESS){
wprintf(L"RASENTRY structure initialization failed!\n");
HeapFree(GetProcessHeap(), 0, lpentry);
return 0;
}
// Validate the new entry's name
dwRet = RasValidateEntryName(NULL, lpszEntry);
if (dwRet != ERROR_SUCCESS){
wprintf(L"RasValidateEntryName failed: Error = %d\n", dwRet);
HeapFree(GetProcessHeap(), 0, lpentry);
return 0;
}
// Create and set the new entry's properties
dwRet = RasSetEntryProperties(NULL, lpszEntry, lpentry, lpentry->dwSize, NULL, 0);
if (dwRet != ERROR_SUCCESS){
wprintf(L"RasSetEntryProperties failed: Error = %d\n", dwRet);
HeapFree(GetProcessHeap(), 0, lpentry);
return 0;
}
/******************************************************************************************/
// Set and get the new entry's credentials
/******************************************************************************************/
// Allocate heap memory for the RASCREDENTIALS structure
LPRASCREDENTIALS lpCred = (LPRASCREDENTIALS) HeapAlloc(GetProcessHeap(), HEAP_ZERO_MEMORY, sizeof(RASCREDENTIALS));
if (lpCred == NULL){
wprintf(L"HeapAlloc failed!\n");
return 0;
}
// The RASCREDENTIALS->dwsize member must be initialized or the RRAS RasSetCredentials() and
// RasGetCredentials() APIs will fail below
lpCred->dwSize = sizeof(RASCREDENTIALS);
// The entry's credentials must first be set with RasSetCredentials() before they can be
// retrieved with RasGetCredentials(). The values below are used to set the new entry's credentials.
dwRet |= StringCchCopyN(lpCred->szDomain, DNLEN, lpszDomainName, DOMAIN_NAME_LENGTH);
dwRet |= StringCchCopyN(lpCred->szUserName, UNLEN, lpszUserName, USER_NAME_LENGTH);
if (dwRet != ERROR_SUCCESS){
wprintf(L"RASCREDENTIALS structure initialization failed!\n");
HeapFree(GetProcessHeap(), 0, lpCred);
return 0;
}
// The username, password, and Domain credentials are valid
lpCred->dwMask = RASCM_UserName | RASCM_Password | RASCM_Domain;
// Set the newly created entry's credentials
dwRet = RasSetCredentials(NULL, lpszEntry, lpCred, FALSE);
// The same RASCREDENTIALS structure is used to 'set' and 'get' the credentials. Therefore, zero out
// its values. (this proves RasGetCredentials works below!)
dwRet |= StringCchCopyN(lpCred->szDomain, DNLEN, L"", 0);
dwRet |= StringCchCopyN(lpCred->szUserName, UNLEN, L"", 0);
dwRet |= StringCchCopyN(lpCred->szPassword, UNLEN, L"", 0);
if (dwRet != ERROR_SUCCESS){
wprintf(L"RASCREDENTIALS structure reset failed!\n");
HeapFree(GetProcessHeap(), 0, lpCred);
HeapFree(GetProcessHeap(), 0, lpentry);
return 0;
}
// Grab the newly created entry's credentials
dwRet = RasGetCredentials(NULL, lpszEntry, lpCred);
if(dwRet == ERROR_SUCCESS){
wprintf(L"The following credentials were retrieved for the entry: %s\n\tUser name: %s\n\tPassword: %s\n\tDomain: %s\n", lpszEntry, lpCred->szUserName, lpCred->szPassword, lpCred->szDomain);
}else{
wprintf(L"RasValidateEntryName failed: Error = %d\n", dwRet);
}
// Clean up: delete the new entry
dwRet = RasDeleteEntry(NULL, lpszEntry);
if (dwRet != ERROR_SUCCESS){
wprintf(L"RasDeleteEntry failed: Error = %d\n", dwRet);
}
HeapFree(GetProcessHeap(), 0, lpentry);
HeapFree(GetProcessHeap(), 0, lpCred);
return 0;
}
Note
L’en-tête ras.h définit RasGetCredentials comme alias qui sélectionne automatiquement la version ANSI ou Unicode de cette fonction en fonction de la définition de la constante de préprocesseur UNICODE. Le mélange de l’utilisation de l’alias neutre en encodage avec du code qui n’est pas neutre en encodage peut entraîner des incompatibilités qui entraînent des erreurs de compilation ou d’exécution. Pour plus d’informations, consultez Conventions pour les prototypes de fonction.
Exigences
| Exigence | Valeur |
|---|---|
| client minimum pris en charge | Windows 2000 Professionnel [applications de bureau uniquement] |
| serveur minimum pris en charge | Windows 2000 Server [applications de bureau uniquement] |
| plateforme cible | Windows |
| d’en-tête | ras.h |
| bibliothèque | Rasapi32.lib |
| DLL | Rasapi32.dll |
Voir aussi
Vue d’ensemble service d’accès à distance (RAS)