Fonction RasEntryDlgA (rasdlg.h)

Article
03/01/2024

La fonction RasEntryDlg affiche des feuilles de propriétés modales qui permettent à un utilisateur de manipuler des entrées de carnet de téléphone. Si vous modifiez ou copiez une entrée d’annuaire téléphonique existante, la fonction affiche une feuille de propriétés d’entrée d’annuaire téléphonique. La fonction RasEntryDlg retourne lorsque l’utilisateur ferme la feuille de propriétés.

Syntaxe

BOOL RasEntryDlgA(
  [in] LPSTR          lpszPhonebook,
  [in] LPSTR          lpszEntry,
  [in] LPRASENTRYDLGA lpInfo
);

Paramètres

[in] lpszPhonebook

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] lpszEntry

Pointeur vers une chaîne terminée par null qui spécifie le nom de l’entrée de l’annuaire téléphonique à modifier, copier ou créer.

Si vous modifiez ou copiez une entrée, ce paramètre est le nom d’une entrée de carnet de téléphone existante. Si vous copiez une entrée, définissez l’indicateur RASEDFLAG_CloneEntry dans le membre dwFlags de la structure RASENTRYDLG .

NoteL’indicateur RASEDFLAG_CloneEntry est déprécié à partir de Windows Vista et Windows Server 2008. Il sera peut-être modifié ou indisponible dans les versions ultérieures. Au lieu de cela, copiez une entrée en appelant RasGetEntryProperties pour obtenir l’entrée, puis en appelant RasSetEntryProperties pour enregistrer l’entrée avec un nouveau nom.

Si vous créez une entrée, ce paramètre est un nouveau nom d’entrée par défaut que l’utilisateur peut modifier. Si ce paramètre a la valeur NULL, la fonction fournit un nom par défaut. Si vous créez une entrée, définissez l’indicateur RASEDFLAG_NewEntry dans le membre dwFlags de la structure RASENTRYDLG .

[in] lpInfo

Pointeur vers une structure RASENTRYDLG qui spécifie des paramètres d’entrée et de sortie supplémentaires. Le membre dwSize de cette structure doit spécifier sizeof(RASENTRYDLG). Utilisez le membre dwFlags pour indiquer si vous créez, modifiez ou copiez une entrée. Si une erreur se produit, le membre dwError retourne un code d’erreur ; sinon, elle retourne zéro.

Valeur retournée

Si l’utilisateur crée, copie ou modifie une entrée de carnet téléphonique, la valeur de retour est TRUE. Sinon, la fonction retourne FALSE.

Si une erreur se produit, RasEntryDlg définit le membre dwError de la structure RASENTRYDLG sur une valeur à partir des codes d’erreur de routage et d’accès à distance ou Winerror.h.

Remarques

Les fonctions RasCreatePhonebookEntry et RasEditPhonebookEntry appellent la fonction RasEntryDlg .

L’exemple de code suivant affiche une feuille de propriétés pour créer une entrée. La variable lpszEntry spécifie le nom par défaut de la nouvelle entrée.

#include <windows.h>
#include <stdio.h>
#include "ras.h"
#include "rasdlg.h"
#include <tchar.h>

DWORD __cdecl wmain(){

    DWORD dwRet = ERROR_SUCCESS;
    BOOL nRet = TRUE;
    LPTSTR lpszEntry = L"EntryName";

    // Allocate heap memory and initialize RASENTRYDLG structure
    LPRASENTRYDLG lpEntry = (LPRASENTRYDLG)HeapAlloc(GetProcessHeap(), HEAP_ZERO_MEMORY, sizeof(RASENTRYDLG));
    if (lpEntry == NULL){
        wprintf(L"HeapAlloc failed.\n");
        return 0;
    }
    
    // The RASENTRYDLG->dwSize member has to be initialized or the RRAS APIs will fail below.
    lpEntry->dwSize = sizeof(RASENTRYDLG);
    lpEntry->dwFlags |= RASEDFLAG_NewEntry;

    // Create the new entry using a user dialog
    nRet = RasEntryDlg(NULL, lpszEntry, lpEntry);

    // Any error codes are returned in lpEntry
    dwRet = lpEntry->dwError;
    
    if (nRet == TRUE) {
        wprintf(L"New entry created: %s\n", lpEntry->szEntry);

        // Clean up: delete the new entry
        dwRet = RasDeleteEntry(NULL, lpszEntry);
        if (dwRet != ERROR_SUCCESS) {
            wprintf(L"RasDeleteEntry failed: Error = %d\n", dwRet);
        }

    } 
    else {
        if (dwRet != ERROR_SUCCESS) {
            wprintf(L"RasEntryDlg failed: Error = %d\n", dwRet);
        }
        else {
            wprintf(L"User pressed Cancel\n");
        }
    }

    HeapFree(GetProcessHeap(), 0, lpEntry);
    return 0;
}

Notes

L’en-tête rasdlg.h définit RASENTRYDLG 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	rasdlg.h
Bibliothèque	Rasdlg.lib
DLL	Rasdlg.dll