Fonction RasDialDlgA (rasdlg.h)
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.
#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 |