Fonction RasDialDlgA (rasdlg.h)

Article
08/25/2023

La fonction RasDialDlg établit une connexion RAS à l’aide d’une entrée d’annuaire téléphonique spécifiée et des informations d’identification de l’utilisateur connecté. La fonction affiche un flux de boîtes de dialogue qui indiquent l’état de l’opération de connexion.

Syntaxe

BOOL RasDialDlgA(
  [in] LPSTR        lpszPhonebook,
  [in] LPSTR        lpszEntry,
  [in] LPSTR        lpszPhoneNumber,
  [in] LPRASDIALDLG 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 d’annuaire téléphonique (PBK). Si ce paramètre a la valeur NULL, la fonction utilise le fichier d’annuaire téléphonique 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 Accès 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 à composer.

[in] lpszPhoneNumber

Pointeur vers une chaîne terminée par null qui spécifie un numéro de téléphone qui remplace les numéros stockés dans l’entrée de l’annuaire téléphonique. Si ce paramètre a la valeur NULL, RasDialDlg utilise les numéros dans l’entrée de l’annuaire téléphonique.

[in] lpInfo

Pointeur vers une structure RASDIALDLG qui spécifie des paramètres d’entrée et de sortie supplémentaires. Le membre dwSize de cette structure doit spécifier sizeof(RASDIALDLG). Si une erreur se produit, le membre dwError retourne un code d’erreur ; sinon, il retourne zéro.

Valeur retournée

Si la fonction établit une connexion RAS, la valeur de retour est TRUE. Sinon, la fonction doit retourner FALSE.

Si une erreur se produit, RasDialDlg doit définir le membre dwError de la structure RASDIALDLG sur une valeur à partir des codes d’erreur de routage et d’accès à distance ou winerror.h.

Remarques

La fonction RasDialDlg affiche une série de boîtes de dialogue similaires aux boîtes de dialogue que la boîte de dialogue réseau à distance main affiche lorsque l’utilisateur sélectionne le bouton Composer. Utilisez la fonction RasDialDlg pour afficher une interface utilisateur standard pour une opération de connexion sans présenter la boîte de dialogue main annuaire téléphonique. Par exemple, le service RAS AutoDial utilise cette fonction pour établir une connexion à l’aide de l’entrée de l’annuaire téléphonique associée à une adresse distante.

La fonction RasDialDlg affiche des boîtes de dialogue pendant l’opération de connexion pour fournir des commentaires à l’utilisateur sur la progression de l’opération. Par exemple, les boîtes de dialogue peuvent indiquer quand l’opération est en cours de numérotation, quand elle authentifie les informations d’identification de l’utilisateur sur le serveur distant, etc. Les boîtes de dialogue fournissent également un bouton Annuler permettant à l’utilisateur de mettre fin à l’opération.

RasDialDlg retourne lorsque la connexion est établie ou lorsque l’utilisateur annule l’opération.

L’exemple de code suivant compose l’entrée dans l’annuaire téléphonique par défaut spécifié par la variable lpszEntry.

Note Cet exemple simple est destiné à s’exécuter sur Windows Vista et les versions ultérieures de Windows. Sachez que l’appel à sizeof(RASENTRY) retourne une valeur différente en fonction de la version du système d’exploitation que le code est en cours d’exécution. Veuillez prendre des mesures pour vous assurer que cela est géré de manière appropriée.

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

#define PHONE_NUMBER_LENGTH 7
#define DEVICE_NAME_LENGTH 5
#define DEVICE_TYPE_LENGTH 5

DWORD __cdecl wmain(){

    DWORD dwError = ERROR_SUCCESS;
    BOOL nRet = TRUE;
    LPTSTR lpszEntry = L"EntryName";
    LPTSTR lpszphonenumber = L"5555555";
    LPTSTR lpszdevicename = L"Modem";
    LPTSTR lpszdevicetype = RASDT_Modem;

    // Allocate heap memory and initialize RASENTRY structure
    LPRASENTRY lpentry = (LPRASENTRY)HeapAlloc(GetProcessHeap(), HEAP_ZERO_MEMORY, sizeof(RASENTRY));
    // Allocate heap memory and initialize RASDIALDLG structure
    LPRASDIALDLG lpInfo = (LPRASDIALDLG) HeapAlloc(GetProcessHeap(), HEAP_ZERO_MEMORY, sizeof(RASDIALDLG));
    
    if (lpentry == NULL || lpInfo == NULL){
        wprintf(L"HeapAlloc failed");
        HeapFree(GetProcessHeap(), 0, lpentry);
        HeapFree(GetProcessHeap(), 0, lpInfo);
        return 0;
    }

    // The RASDIALDLG and RASENTRY dwSize members have to be initialized or the RasDialDlg()
    // RasSetEntryProperties() APIs will fail below.
    lpInfo->dwSize = sizeof(RASDIALDLG);
    lpentry->dwSize = sizeof(RASENTRY);
    lpentry->dwFramingProtocol = RASFP_Ppp;
    lpentry->dwfOptions = 0;
    lpentry->dwType = RASFP_Ppp;
    dwError |= StringCchCopyN(lpentry->szLocalPhoneNumber, RAS_MaxPhoneNumber, lpszphonenumber, PHONE_NUMBER_LENGTH);
    dwError |= StringCchCopyN(lpentry->szDeviceName, RAS_MaxDeviceName, lpszdevicename, DEVICE_NAME_LENGTH);
    dwError |= StringCchCopyN(lpentry->szDeviceType, RAS_MaxDeviceType, lpszdevicetype, DEVICE_TYPE_LENGTH);
    
    if (dwError != S_OK){
        wprintf(L"Structure initialization failed: Error = %d\n", dwError);
        HeapFree(GetProcessHeap(), 0, lpentry);
        HeapFree(GetProcessHeap(), 0, lpInfo);
        return 0;
    }

    // Validate the new entry's name
    dwError = RasValidateEntryName(NULL, lpszEntry);
    if (dwError != ERROR_SUCCESS){
        wprintf(L"RasValidateEntryName failed: Error = %d\n", dwError);
        HeapFree(GetProcessHeap(), 0, lpentry);
        HeapFree(GetProcessHeap(), 0, lpInfo);
        return 0;
    }

    // Create and set the new entry's properties
    dwError = RasSetEntryProperties(NULL, lpszEntry, lpentry, lpentry->dwSize, NULL, 0);
    if (dwError != ERROR_SUCCESS){
        wprintf(L"RasSetEntryProperties failed: Error = %d\n", dwError);
        HeapFree(GetProcessHeap(), 0, lpentry);
        HeapFree(GetProcessHeap(), 0, lpInfo);
        return 0;
    }
    
    // Connect using the new entry
    nRet = RasDialDlg(NULL, lpszEntry, NULL, lpInfo);
    if (nRet != TRUE){
        wprintf(L"RasDialDlg failed: Error = %d\n", lpInfo->dwError);
    }
    
    // Clean up: delete the new entry
    dwError = RasDeleteEntry(NULL, lpszEntry);
    if (dwError != ERROR_SUCCESS){
        wprintf(L"RasDeleteEntry failed: Error = %d\n", dwError);
    }
    
    HeapFree(GetProcessHeap(), 0, lpentry);
    HeapFree(GetProcessHeap(), 0, lpInfo);

    return 0;
}

Notes

L’en-tête rasdlg.h définit RasDialDlg comme un 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.

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

Voir aussi

RASDIALDLG

RasPhonebookDlg

Vue d’ensemble du service d’accès à distance (RAS)

Fonctions du service d’accès à distance

Partager via