Fonction RasGetCredentialsA (ras.h)
La fonction RasGetCredentials récupère les informations d’identification de l’utilisateur associées à une entrée de téléphone 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 terminée par null qui spécifie le chemin d’accès complet et le nom de fichier d’un fichier d’annuaire téléphonique (PBK). Si ce paramètre a la valeur NULL, la fonction utilise le fichier d’annuaire téléphonique par défaut actuel. Le fichier d’annuaire 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 Accès réseau à distance.
[in] unnamedParam2
Pointeur vers une chaîne terminée par null qui spécifie le nom d’une entrée de répertoire téléphonique.
[in, out] unnamedParam3
Pointeur vers la structure RASCREDENTIALS qui, lors de la sortie, reçoit les informations d’identification de l’utilisateur associées à l’entrée de l’annuaire téléphonique spécifiée.
Lors de l’entrée, définissez le membre dwSize de la structure sur sizeof(RASCREDENTIALS) et définissez le membre dwMask pour indiquer les informations d’identification à récupérer. Lorsque la fonction retourne, dwMask indique les membres qui ont été récupérés avec succès.
Valeur retournée
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 provenant des codes d’erreur de routage et d’accès à distance ou de Winerror.h.
| Valeur | Signification |
|---|---|
|
L’annuaire téléphonique spécifié est introuvable. |
|
L’entrée spécifiée n’existe pas dans l’annuaire téléphonique. |
|
Le paramètre lpCredentials était NULL. |
|
Le membre dwSize de la structure RASCREDENTIALS est une valeur non reconnue. |
Notes
La fonction RasGetCredentials récupère les informations d’identification du dernier utilisateur afin de se connecter à l’aide de l’entrée de l’annuaire téléphonique spécifiée, ou des informations d’identification spécifiées ultérieurement dans un appel à la fonction RasSetCredentials pour l’entrée de l’annuaire téléphonique.
Cette fonction est le moyen par défaut de récupérer de manière sécurisée les informations d’identification associées à une entrée d’annuaire téléphonique RAS. RasGetCredentials remplace la fonction RasGetEntryDialParams , qui peut ne pas être prise en charge dans les versions ultérieures de Windows.
RasGetCredentials ne retourne pas le mot de passe réel. Au lieu de cela, le membre szPassword de la structure RASCREDENTIALS contient un handle du mot de passe enregistré. Remplacez ce handle par le mot de passe enregistré dans les appels suivants à RasSetCredentials et RasDial. Lorsqu’il est présenté avec ce handle, RasDial récupère et utilise le mot de passe enregistré. La valeur de ce handle peut changer dans les versions futures 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 RASCREDENTIALS 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 aucun 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 le 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 d’annuaire téléphonique « 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;
}
Notes
L’en-tête ras.h définit RasGetCredentials comme un 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.
Spécifications
| Client minimal pris en charge | Windows 2000 Professionnel [applications de bureau uniquement] |
| Serveur minimal pris en charge | Windows 2000 Server [applications de bureau uniquement] |
| Plateforme cible | Windows |
| En-tête | ras.h |
| Bibliothèque | Rasapi32.lib |
| DLL | Rasapi32.dll |
Voir aussi
Commentaires
Bientôt disponible : Tout au long de 2024, nous allons supprimer progressivement GitHub Issues comme mécanisme de commentaires pour le contenu et le remplacer par un nouveau système de commentaires. Pour plus d’informations, consultez https://aka.ms/ContentUserFeedback.
Envoyer et afficher des commentaires pour