RasSetCredentialsA, fonction (ras.h)

Article
11/20/2024

La fonction RasSetCredentials définit les informations d’identification de l’utilisateur associées à une entrée de livre téléphonique RAS spécifiée.

Syntaxe

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

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 PBK (Phone-Book). Si ce paramètre est NULL, la fonction utilise le fichier de livre téléphonique par défaut actuel. Le fichier de carnet 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 Mise en réseau rendez-vous.

[in] unnamedParam2

Pointeur vers une chaîne terminée par null qui spécifie le nom d’une entrée de livre téléphonique.

[in] unnamedParam3

Pointeur vers une structure RASCREDENTIALS qui spécifie les informations d’identification de l’utilisateur à définir pour l’entrée de livre téléphonique spécifiée. Avant d’appeler RasSetCredentials, définissez le membre dwSize de la structure sur sizeof(RASCREDENTIALS) et définissez le membre dwMask pour indiquer les informations d’identification à définir.

[in] unnamedParam4

Valeur qui spécifie si RasSetCredentials efface les informations d’identification existantes en les définissant sur la chaîne vide « ». Si cet indicateur est TRUE, le membre dwMask de la structure RASCREDENTIALS indique les informations d’identification que la fonction définit sur la chaîne vide. Si cet indicateur est FALSE, la fonction définit les informations d’identification indiquées en fonction du contenu de leurs RASCREDENTIALS correspondantes membres.

Valeur de retour

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 de Codes d’erreur de routage et d’accès à distance ou WinError.h.

Valeur	Signification
ERROR_CANNOT_OPEN_PHONEBOOK	Le carnet de téléphone spécifié est introuvable.
ERROR_INVALID_PARAMETER	Le paramètre lpCredentials était NULL, ou l’entrée spécifiée n’existe pas dans le carnet de téléphones.
ERROR_ACCESS_DENIED	L’une des conditions suivantes s’est produite : L’application appelante a tenté de définir les informations d’identification par défaut pour une connexion par utilisateur. Les informations d’identification par défaut ne peuvent être définies que pour une connexion à tous les utilisateurs. L’utilisateur n’a pas les privilèges appropriés pour définir des clés ou des informations d’identification prédéfinies pour tous les utilisateurs en cas de connectoids tous les utilisateurs. Seuls les administrateurs peuvent effectuer ces tâches.

Remarques

La fonction RasSetCredentials définit les informations d’identification de l’utilisateur associées à une entrée de livre téléphonique RAS spécifiée. Les informations d’identification stockées avec une entrée de carnet téléphonique sont les informations d’identification du dernier utilisateur pour se connecter avec succès à l’aide de l’entrée de carnet téléphonique spécifiée, ou les informations d’identification spécifiées par la suite dans un appel aux RasSetCredentials ou RasSetEntryDialParams fonction pour l’entrée de carnet téléphonique.

La fonction RasSetCredentials est le moyen préféré de stocker en toute sécurité les informations d’identification avec une entrée par téléphone. RasSetCredentials remplace la fonction RasSetEntryDialParams, qui peut ne pas être prise en charge dans les versions ultérieures du système d’exploitation Windows.

Un handle de mot de passe est « **************** » (16 astérisques). Si vous appelez RasGetCredentials et recevez 16 *s dans le champ de mot de passe, vous avez un mot de passe stocké et, pour des raisons de sécurité, il ne vous sera pas remis en texte brut. Si le membre szPassword de la structure RASCREDENTIALS contient le handle de mot de passe (16 *s) retourné par RasGetCredentials ou RasGetEntryDialParams, l’appel suivant à RasSetCredentials ne modifie pas le mot de passe enregistré.

Pour définir les informations d’identification par défaut d’une connexion à tous les utilisateurs, définissez l’indicateur RASCM_DefaultCreds dans le membre dwMask du RASCREDENTIALS structure pointée par le paramètre lpCredentials. Si vous tentez de définir les informations d’identification par défaut pour une connexion par utilisateur, RasSetCredentials retourne ERROR_ACCESS_DENIED.

Lorsque vous définissez des informations d’identification pour une connexion à tous les utilisateurs, si l’application appelante spécifie une valeur non NULL pour le paramètre phone-book, lpszPhonebook, le fichier phone-book doit se trouver dans le répertoire phone-book sous le chemin des données de l’application tous les utilisateurs. Pour obtenir l’emplacement approprié pour le fichier de carnet téléphonique, appelez d’abord SHGetFolderPath avec une valeur CSIDL de CSIDL_COMMON_APPDATA. SHGetFolderPath retourne le chemin des données de l’application tous les utilisateurs. Ajoutez la chaîne suivante à ce chemin d’accès :

Microsoft\Network\Connections\Pbk

Le chemin combiné est l’emplacement approprié pour le fichier de livres téléphoniques.

Remarque Spécifier une valeur non NULL pour le paramètre lpszPhonebook peut ne pas être pris en charge dans les versions ultérieures du système d’exploitation Windows.

Pour définir une clé pré-partagée, utilisez l’indicateur RASCM_PreSharedKey dans la RASCREDENTIALS. champdwMask.

Note

L’en-tête ras.h définit RasSetCredentials comme 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.

Exigences

Exigence	Valeur
client minimum pris en charge	Windows 2000 Professionnel [applications de bureau uniquement]
serveur minimum pris en charge	Windows 2000 Server [applications de bureau uniquement]
plateforme cible	Windows
d’en-tête	ras.h
bibliothèque	Rasapi32.lib
DLL	Rasapi32.dll