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.
| Valor | Significado |
|---|---|
|
No se encuentra la libreta de teléfonos especificada. |
|
La entrada especificada no existe en la libreta de teléfonos. |
|
El parámetro lpCredentials era NULL. |
|
El miembro dwSize de la estructura RASCREDENTIALS es un valor no reconocido. |
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;
}
Nota:
El encabezado ras.h define RasGetCredentials como alias que selecciona automáticamente la versión ANSI o Unicode de esta función en función de la definición de la constante de preprocesador UNICODE. La combinación del uso del alias neutro de codificación con código que no es neutral de codificación puede provocar discrepancias que dan lugar a errores de compilación o en tiempo de ejecución. Para obtener más información, vea Convenciones para prototipos de función.
Requisitos
| Cliente mínimo compatible | Windows 2000 Professional [solo aplicaciones de escritorio] |
| Servidor mínimo compatible | Windows 2000 Server [solo aplicaciones de escritorio] |
| Plataforma de destino | Windows |
| Encabezado | ras.h |
| Library | Rasapi32.lib |
| Archivo DLL | Rasapi32.dll |
Consulte también
Información general sobre el servicio de acceso remoto (RAS)
Comentarios
Próximamente: A lo largo de 2024 iremos eliminando gradualmente GitHub Issues como mecanismo de comentarios sobre el contenido y lo sustituiremos por un nuevo sistema de comentarios. Para más información, vea: https://aka.ms/ContentUserFeedback.
Enviar y ver comentarios de