RasSetEntryPropertiesA, fonction (ras.h)

Article
08/25/2023

La fonction RasSetEntryProperties modifie les informations de connexion d’une entrée dans l’annuaire téléphonique ou crée une nouvelle entrée de carnet de téléphone.

Syntaxe

DWORD RasSetEntryPropertiesA(
  [in] LPCSTR      unnamedParam1,
  [in] LPCSTR      unnamedParam2,
  [in] LPRASENTRYA unnamedParam3,
  [in] DWORD       unnamedParam4,
  [in] LPBYTE      unnamedParam5,
  [in] DWORD       unnamedParam6
);

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 un nom d’entrée.

Si le nom de l’entrée correspond à une entrée existante, RasSetEntryProperties modifie les propriétés de cette entrée.

Si le nom de l’entrée ne correspond pas à une entrée existante, RasSetEntryProperties crée une nouvelle entrée d’annuaire téléphonique. Pour les nouvelles entrées, appelez la fonction RasValidateEntryName pour valider le nom de l’entrée avant d’appeler RasSetEntryProperties.

[in] unnamedParam3

Pointeur vers la structure RASENTRY qui spécifie les nouvelles données de connexion à associer à l’entrée de l’annuaire téléphonique indiquée par le paramètre lpszEntry .

L’appelant doit fournir des valeurs pour les membres suivants dans la structure RASENTRY .

dwSize
szLocalPhoneNumber
szDeviceName
szDeviceType
dwFramingProtocol
dwfOptions
dwType

Windows XP ou version ultérieure : dwType est pris en charge.

Si aucune valeur n’est fournie pour ces membres, RasSetEntryProperties échoue avec ERROR_INVALID_PARAMETER.

La structure peut être suivie d’un tableau de chaînes de numéro de téléphone alternatives terminées par null. La dernière chaîne est terminée par deux caractères null consécutifs. Le membre dwAlternateOffset de la structure RASENTRY contient le décalage de la première chaîne.

[in] unnamedParam4

Spécifie la taille, en octets, de la mémoire tampon identifiée par le paramètre lpRasEntry .

[in] unnamedParam5

Pointeur vers une mémoire tampon qui spécifie des informations de configuration spécifiques à l’appareil. Il s’agit d’informations opaques sur la configuration de l’appareil TAPI. Pour plus d’informations sur la configuration de l’appareil TAPI, consultez la fonction lineGetDevConfig dans Les interfaces de programmation d’applications de téléphonie (TAPI) dans le Kit de développement logiciel (SDK) de plateforme.

Windows XP : Ce paramètre n’est pas utilisé. La fonction appelante doit définir ce paramètre sur NULL.

[in] unnamedParam6

Spécifie la taille, en octets, de la mémoire tampon lpbDeviceInfo .

Windows XP : Ce paramètre n’est pas utilisé. La fonction appelante doit définir ce paramètre sur zéro.

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_ACCESS_DENIED	L’utilisateur ne dispose pas des privilèges appropriés. Seul un administrateur peut effectuer cette tâche.
ERROR_BUFFER_INVALID	L’adresse ou la mémoire tampon spécifiée par lpRasEntry n’est pas valide.
ERROR_CANNOT_OPEN_PHONEBOOK	L’annuaire téléphonique est endommagé ou des composants manquants.
ERROR_INVALID_PARAMETER	La structure RASENTRY pointée par le paramètre lpRasEntry ne contient pas d’informations adéquates ou l’entrée spécifiée n’existe pas dans l’annuaire téléphonique. Consultez la description de lpRasEntry pour connaître les informations requises.

Remarques

Lors de la définition des propriétés d’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 phone-book 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 de Windows ultérieures à Windows XP.

Notes

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

Configuration requise

Condition requise	Valeur
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