Función RasGetCredentialsA (ras.h)

La función RasGetCredentials recupera las credenciales de usuario asociadas a una entrada de libreta de teléfono RAS especificada.

Sintaxis

DWORD RasGetCredentialsA(
  [in]      LPCSTR            unnamedParam1,
  [in]      LPCSTR            unnamedParam2,
  [in, out] LPRASCREDENTIALSA unnamedParam3
);

Parámetros

[in] unnamedParam1

Puntero a una cadena terminada en null que especifica la ruta de acceso completa y el nombre de archivo de un archivo de libreta de teléfonos (PBK). Si este parámetro es NULL, la función usa el archivo de libreta de teléfonos predeterminado actual. El archivo de libreta telefónica predeterminado es el seleccionado por el usuario en la hoja de propiedades Preferencias de usuario del cuadro de diálogo Redes de acceso telefónico .

[in] unnamedParam2

Puntero a una cadena terminada en null que especifica el nombre de una entrada de libreta de teléfonos.

[in, out] unnamedParam3

Puntero a la estructura RASCREDENTIALS que, en la salida, recibe las credenciales de usuario asociadas a la entrada de libreta de teléfono especificada.

En la entrada, establezca el miembro dwSize de la estructura en sizeof(RASCREDENTIALS) y establezca el miembro dwMask para indicar la información de credenciales que se va a recuperar. Cuando la función devuelve, dwMask indica los miembros que se recuperaron correctamente.

Valor devuelto

Si la función se ejecuta correctamente, el valor devuelto es ERROR_SUCCESS.

Si se produce un error en la función, el valor devuelto es uno de los siguientes códigos de error o un valor de Enrutamiento y códigos de error de acceso remoto o Winerror.h.

Comentarios

La función RasGetCredentials recupera las credenciales del último usuario para conectarse mediante la entrada de la libreta de teléfono especificada, o las credenciales especificadas posteriormente en una llamada a la función RasSetCredentials para la entrada de la libreta de teléfonos.

Esta función es la forma preferida de recuperar de forma segura las credenciales asociadas a una entrada de libreta de teléfono ras. RasGetCredentials reemplaza a la función RasGetEntryDialParams , que puede que no se admita en futuras versiones de Windows.

RasGetCredentials no devuelve la contraseña real. En su lugar, el miembro szPassword de la estructura RASCREDENTIALS contiene un identificador para la contraseña guardada. Sustituya este identificador por la contraseña guardada en llamadas posteriores a RasSetCredentials y RasDial. Cuando se presenta este identificador, RasDial recupera y usa la contraseña guardada. El valor de este identificador puede cambiar en versiones futuras del sistema operativo; no desarrolle código que dependa del contenido o el formato de este valor.

El miembro dwMask de RASCREDENTIALS contiene la marca RASCM_Password si el sistema ha guardado una contraseña para la entrada especificada. Si el sistema no tiene ninguna contraseña guardada para esta entrada, dwMask no contiene RASCM_Password.

Windows 2000/NT: Esta característica no se admite.

Si dwMask de la estructura RASCREDENTIALS contiene la marca de RASCM_DefaultCreds, las credenciales devueltas son las credenciales predeterminadas para una conexión de todos los usuarios.

Para recuperar una clave precompartida, use la marca RASCM_PreSharedKey en el campo RASCREDENTIALS.dwMask.

Windows 2000/NT: Esta característica no se admite.

El código de ejemplo siguiente crea la entrada de la libreta de teléfonos "RasEntryName", establece sus credenciales mediante RasSetCredentials y, a continuación, recupera esas credenciales mediante 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;
}

Requisitos

Consulte también

RASCREDENTIALS

RasGetEntryDialParams

RasSetCredentials

Información general sobre el servicio de acceso remoto (RAS)

Funciones del Servicio de acceso remoto