RasSetCredentialsA, fonction (ras.h)

Article
08/25/2023

La fonction RasSetCredentials définit les informations d’identification de l’utilisateur associées à une entrée de carnet de téléphone 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 a la valeur NULL, la fonction utilise le fichier d’annuaire 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 Mise en réseau à distance .

[in] unnamedParam2

Pointeur vers une chaîne terminée par null qui spécifie le nom d’une entrée d’annuaire 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 carnet de téléphone spécifiée. Avant d’appeler RasSetCredentials, définissez le membre dwSize de la structure sizeof(RASCREDENTIALS) sur 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 a la valeur 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 a la valeur FALSE, la fonction définit les informations d’identification indiquées en fonction du contenu de leurs membres RASCREDENTIALS correspondants .

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

Valeur	Signification
ERROR_CANNOT_OPEN_PHONEBOOK	L’annuaire téléphonique spécifié est introuvable.
ERROR_INVALID_PARAMETER	Le paramètre lpCredentials était NULL, ou l’entrée spécifiée n’existe pas dans l’annuaire téléphonique.
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 peuvent être définies uniquement pour une connexion à tous les utilisateurs. L’utilisateur ne dispose pas des privilèges appropriés pour définir des clés ou des informations d’identification pré-partagées pour tous les utilisateurs en cas de connectoids tous les utilisateurs. Seuls les administrateurs peuvent effectuer ces tâches.

Notes

La fonction RasSetCredentials définit les informations d’identification de l’utilisateur associées à une entrée de carnet de téléphone RAS spécifiée. Les informations d’identification stockées avec une entrée de carnet de téléphone sont les informations d’identification du dernier utilisateur qui a réussi à se connecter à l’aide de l’entrée de carnet de téléphone spécifiée, ou les informations d’identification spécifiées ultérieurement dans un appel à la fonction RasSetCredentials ou RasSetEntryDialParams pour l’entrée de carnet de téléphone.

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

Un descripteur de mot de passe est « ****** » (16 astérisques). Si vous appelez RasGetCredentials et recevez 16 *s dans le champ de mot de passe, vous disposez d’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 de la structure RASCREDENTIALS vers laquelle pointe 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.

Lors de la définition des informations d’identification pour une connexion tous les utilisateurs, si l’application appelante spécifie une valeur non NULL pour le paramètre d’annuaire téléphonique, lpszPhonebook, le fichier de l’annuaire téléphonique doit se trouver dans le répertoire de l’annuaire téléphonique sous le chemin des données de l’application tous les utilisateurs. Pour obtenir l’emplacement correct du fichier d’annuaire téléphonique, appelez d’abord SHGetFolderPath avec une valeur CSIDLde 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 d’accès combiné est l’emplacement approprié pour le fichier de l’annuaire téléphonique.

Note La spécification d’une valeur non NULL pour le paramètre lpszPhonebook peut ne pas être prise 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 RASCREDENTIALS. Champ dwMask .

Notes

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