RasSetEntryPropertiesA, fonction (ras.h)

Article
11/20/2024

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

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

Si le nom d’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 entrée de carnet téléphonique. Pour les nouvelles entrées, appelez la fonction RasValidateEntryName pour valider le nom d’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 carnet 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 les valeurs ne sont pas fournies pour ces membres, RasSetEntryProperties échoue avec ERROR_INVALID_PARAMETER.

La structure peut être suivie d’un tableau de chaînes de numéros de téléphone alternatifs terminées par null. La dernière chaîne est arrêtée par deux caractères null consécutifs. La dwAlternateOffset membre de la structure RASENTRY contient le décalage vers 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 de configuration d’appareil TAPI opaques. Pour plus d’informations sur la configuration de l’appareil TAPI, consultez la fonction lineGetDevConfig dans l’interface TAPI (Téléphonie Application Programming Interfaces) 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 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_ACCESS_DENIED	L’utilisateur n’a pas les 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	Le carnet de téléphones est endommagé ou manquant.
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 le livre téléphonique. Consultez la description de lpRasEntry pour voir quelles informations sont requises.

Remarques

Lorsque vous définissez des propriétés pour une connexion à tous les utilisateurs, si l’application appelante spécifie une valeur de NULL non-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 de NULL nonpour le paramètre lpszPhonebook peut ne pas être pris en charge dans les versions de Windows ultérieures à Windows XP.

Note

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