RasSetEntryDialParamsA, fonction (ras.h)

Article
11/20/2024

La fonction RasSetEntryDialParams modifie les informations de connexion enregistrées par le dernier appel réussi au RasDial ou RasSetEntryDialParams fonction pour une entrée de livre téléphonique spécifiée.

Syntaxe

DWORD RasSetEntryDialParamsA(
  [in] LPCSTR           unnamedParam1,
  [in] LPRASDIALPARAMSA unnamedParam2,
  [in] BOOL             unnamedParam3
);

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.

Windows Me/98/95 : Ce paramètre doit toujours être NULL. La mise en réseau rendez-vous stocke les entrées de livres téléphoniques dans le Registre plutôt que dans un fichier de livres téléphoniques.

[in] unnamedParam2

Pointeur vers la structure RASDIALPARAMS qui spécifie les paramètres de connexion à associer à l’entrée de carnet téléphonique. RasSetEntryDialParams utilise les membres de la structure comme suit.

Membre	Signification
dwSize	Doit spécifier la taille de (RASDIALPARAMS) pour identifier la version de la structure.
szEntryName	Chaîne terminée par null qui identifie l’entrée de carnet téléphonique pour laquelle définir les paramètres.
szPhoneNumber	Non utilisé. Défini sur NULL .
szCallbackNumber	Chaîne terminée par null qui contient le numéro de téléphone de rappel. Si szCallbackNumber est une chaîne vide ( " ), le numéro de rappel n’est pas modifié.
szUserName	Chaîne terminée par null qui contient le nom d’ouverture de session de l’utilisateur associé à cette entrée. Si szUserName est une chaîne vide, le nom d’utilisateur n’est pas modifié.
szPassword	Chaîne terminée par null qui contient le mot de passe de l’utilisateur spécifié par szUserName. Si szUserName est une chaîne vide, le mot de passe n’est pas modifié. Si szPassword est une chaîne vide et fRemovePassword est FALSE, le mot de passe est défini sur la chaîne vide. Si fRemovePassword est TRUE, le mot de passe stocké dans cette entrée de carnet téléphonique pour l’utilisateur spécifié par szUserName est supprimé quel que soit le contenu de la chaîne szPassword. Windows NT 4.0 : Le mot de passe est remplacé par la chaîne spécifiée par szPassword, que szUserName soit une chaîne vide. Windows XP/2000 : Si szPassword contient le handle de mot de passe retourné par RasGetCredentials ou RasGetEntryDialParams, RasSetEntryDialParams retourne correctement sans modifier de mot de passe actuellement enregistré.
szDomain	Chaîne terminée par null qui contient le nom du domaine sur lequel se connecter. Si szDomain est une chaîne vide, le nom de domaine n’est pas modifié.
dwSubEntry	Spécifie l’index (basé sur un) de la sous-entrée initiale à composer lors de l’établissement de la connexion.
dwCallbackId	Spécifie une valeur définie par l’application que RAS passe à la fonction de rappel RasDialFunc2.

[in] unnamedParam3

Spécifie s’il faut supprimer le mot de passe stocké de l’entrée de carnet téléphonique pour l’utilisateur indiqué par lprasdialparams->szUserName. Si fRemovePassword est TRUE, le mot de passe est supprimé. La définition de fRemovePassword sur TRUE équivaut à cocher la case « Annuler le mot de passe » dans la mise en réseau rendez-vous. Lorsque vous définissez le mot de passe ou d’autres propriétés d’une entrée de carnet de téléphone, définissez fRemovePassword sur FALSE.

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 d’acheminement et d’accès à distance ou Winerror.h.

Valeur	Description
ERROR_BUFFER_INVALID	L’adresse ou la mémoire tampon spécifiée par lprasdialparams n’est pas valide.
ERROR_CANNOT_OPEN_PHONEBOOK	Le carnet de téléphones est endommagé ou manquant.
ERROR_CANNOT_FIND_PHONEBOOK_ENTRY	L’entrée par téléphone n’existe pas.

Remarques

Pour créer une entrée de carnet téléphonique, utilisez la fonction RasSetEntryProperties.

Windows XP ou version ultérieure : n’utilisez pas la fonction RasSetEntryDialParams. Pour définir les informations d’identification d’une entrée de carnet téléphonique, utilisez la fonction RasSetCredentials. Définissez les membres non-credential de RASDIALPARAMS (par exemple szCallbackNumber, dwSubEntryou dwCallbackId) directement dans la structure RASDIALPARAMS passée en tant que paramètre à la fonction RasDial.

Note

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