Función RasSetCredentialsA (ras.h)

Artículo
08/25/2023

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

Sintaxis

DWORD RasSetCredentialsA(
  [in] LPCSTR            unnamedParam1,
  [in] LPCSTR            unnamedParam2,
  [in] LPRASCREDENTIALSA unnamedParam3,
  [in] BOOL              unnamedParam4
);

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 telefónica (PBK). Si este parámetro es NULL, la función usa el archivo de libreta telefónica 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 la libreta de teléfonos.

[in] unnamedParam3

Puntero a una estructura RASCREDENTIALS que especifica las credenciales de usuario que se van a establecer para la entrada de la libreta de teléfono especificada. Antes de llamar a RasSetCredentials, establezca el miembro dwSize de la estructura sizeof(RASCREDENTIALS) en y establezca el miembro dwMask para indicar la información de credenciales que se va a establecer.

[in] unnamedParam4

Valor que especifica si RasSetCredentials borra las credenciales existentes estableciendolas en la cadena vacía, "". Si esta marca es TRUE, el miembro dwMask de la estructura RASCREDENTIALS indica qué credenciales establece la función en la cadena vacía. Si esta marca es FALSE, la función establece las credenciales indicadas según el contenido de sus miembros RASCREDENTIALS correspondientes .

Valor devuelto

Si la función se ejecuta correctamente, el valor devuelto se 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 Códigos de error de enrutamiento y acceso remoto o WinError.h.

Valor	Significado
ERROR_CANNOT_OPEN_PHONEBOOK	No se encuentra la libreta de teléfonos especificada.
ERROR_INVALID_PARAMETER	El parámetro lpCredentials era NULL o la entrada especificada no existe en la libreta de teléfonos.
ERROR_ACCESS_DENIED	Se produjo una de las condiciones siguientes: La aplicación que llama intentó establecer las credenciales predeterminadas para una conexión por usuario. Las credenciales predeterminadas solo se pueden establecer para una conexión de todos los usuarios. El usuario no tiene los privilegios correctos para establecer claves o credenciales precompartidas para todos los usuarios en caso de connectoids de todos los usuarios. Solo los administradores pueden completar estas tareas.

Comentarios

La función RasSetCredentials establece las credenciales de usuario asociadas a una entrada de libreta de teléfono RAS especificada. Las credenciales almacenadas con una entrada de libreta de teléfono son las credenciales del último usuario para conectarse correctamente mediante la entrada de libreta de teléfono especificada, o las credenciales especificadas posteriormente en una llamada a la función RasSetCredentials o RasSetEntryDialParams para la entrada de la libreta de teléfonos.

La función RasSetCredentials es la forma preferida de almacenar de forma segura las credenciales con una entrada de libreta de teléfonos. RasSetCredentials sustituye a la función RasSetEntryDialParams , que puede que no se admita en futuras versiones del sistema operativo Windows.

Un identificador de contraseña es "************" (16 asteriscos). Si llama a RasGetCredentials y recibe 16 *s de vuelta en el campo de contraseña, tiene una contraseña almacenada y, por motivos de seguridad, no se le devolverá en texto sin formato. Si el miembro szPassword de la estructura RASCREDENTIALS contiene el identificador de contraseña (16 *s) devuelto por RasGetCredentials o RasGetEntryDialParams, la siguiente llamada a RasSetCredentials no cambiará la contraseña guardada.

Para establecer las credenciales predeterminadas para una conexión de todo el usuario, establezca la marca RASCM_DefaultCreds en el miembro dwMask de la estructura RASCREDENTIALS a la que apunta el parámetro lpCredentials . Si intenta establecer credenciales predeterminadas para una conexión por usuario, RasSetCredentials devuelve ERROR_ACCESS_DENIED.

Al establecer las credenciales para una conexión de todos los usuarios, si la aplicación que realiza la llamada especifica un valor distinto de NULL para el parámetro phone-book, lpszPhonebook, el archivo de libreta de teléfonos debe encontrarse en el directorio de libreta de teléfonos debajo de la ruta de acceso de datos de la aplicación todos los usuarios. Para obtener la ubicación correcta para el archivo de libreta de teléfonos, llame primero a SHGetFolderPath con un valor CSIDL de CSIDL_COMMON_APPDATA. SHGetFolderPath devuelve la ruta de acceso de datos de la aplicación de todos los usuarios. Anexe la cadena siguiente a esta ruta de acceso:

Microsoft\Network\Connections\Pbk

La ruta de acceso combinada es la ubicación correcta para el archivo de libreta telefónica.

Nota Es posible que no se admita la especificación de un valor distinto de NULL para el parámetro lpszPhonebook en versiones posteriores del sistema operativo Windows.

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

Nota:

El encabezado ras.h define RasSetCredentials 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 neutral de codificación con código que no es neutral de codificación puede dar lugar a errores de coincidencia que dan lugar a errores de compilación o 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