Fonction RasGetCredentialsA (ras.h)

Article
08/25/2023

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
ERROR_CANNOT_OPEN_PHONEBOOK	L’annuaire téléphonique spécifié est introuvable.
ERROR_CANNOT_FIND_PHONEBOOK_ENTRY	L’entrée spécifiée n’existe pas dans l’annuaire téléphonique.
ERROR_INVALID_PARAMETER	Le paramètre lpCredentials était NULL.
ERROR_INVALID_SIZE	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

RASCREDENTIALS

RasGetEntryDialParams

RasSetCredentials

Vue d’ensemble du service d’accès à distance (RAS)

Fonctions du service d’accès à distance

Partager via

Fonction RasGetCredentialsA (ras.h)

Syntaxe

Paramètres

Valeur retournée

Notes

Spécifications

Voir aussi

Commentaires

Ressources supplémentaires