RasDialDlgA-Funktion (rasdlg.h)

Artikel
03/01/2024

Die RasDialDlg-Funktion stellt mithilfe eines angegebenen Telefonbucheintrags und der Anmeldeinformationen des angemeldeten Benutzers eine RAS-Verbindung her. Die Funktion zeigt einen Stream von Dialogfeldern an, die den Status des Verbindungsvorgangs angeben.

Syntax

BOOL RasDialDlgA(
  [in] LPSTR        lpszPhonebook,
  [in] LPSTR        lpszEntry,
  [in] LPSTR        lpszPhoneNumber,
  [in] LPRASDIALDLG lpInfo
);

Parameter

[in] lpszPhonebook

Zeiger auf eine NULL-endende Zeichenfolge, die den vollständigen Pfad und Dateinamen einer Telefonbuchdatei (PBK) angibt. Wenn dieser Parameter NULL ist, verwendet die Funktion die aktuelle Standardtelefonbuchdatei. Die Standardmäßige Telefonbuchdatei wird vom Benutzer im Eigenschaftenblatt Benutzereinstellungen des DialogfeldsDFÜ-Netzwerk ausgewählt.

[in] lpszEntry

Zeiger auf eine NULL-endende Zeichenfolge, die den Namen des zu wählenden Telefonbucheintrags angibt.

[in] lpszPhoneNumber

Zeiger auf eine NULL-endende Zeichenfolge, die eine Telefonnummer angibt, die die im Telefonbucheintrag gespeicherten Nummern überschreibt. Wenn dieser Parameter NULL ist, verwendet RasDialDlg die Nummern im Telefonbucheintrag.

[in] lpInfo

Zeiger auf eine RASDIALDLG-Struktur , die zusätzliche Eingabe- und Ausgabeparameter angibt. Der dwSize-Member dieser Struktur muss sizeof(RASDIALDLG) angeben. Wenn ein Fehler auftritt, gibt der dwError-Member einen Fehlercode zurück. Andernfalls wird 0 (null) zurückgegeben.

Rückgabewert

Wenn die Funktion eine RAS-Verbindung herstellt, ist der Rückgabewert TRUE. Andernfalls sollte die Funktion FALSE zurückgeben.

Wenn ein Fehler auftritt, sollte RasDialDlg den dwError-Member der RASDIALDLG-Struktur auf einen Wert aus Routing- und RAS-Fehlercodes oder Winerror.h festlegen.

Hinweise

Die RasDialDlg-Funktion zeigt eine Reihe von Dialogfeldern an, die den Dialogfeldern ähneln, die im Dialogfeld Standard DFÜ-Netzwerk angezeigt werden, wenn der Benutzer die Schaltfläche Wählen auswählt. Verwenden Sie die RasDialDlg-Funktion, um eine Standardbenutzeroberfläche für einen Verbindungsvorgang anzuzeigen, ohne das Dialogfeld Standard Telefonbuch anzuzeigen. Der RAS AutoDial-Dienst verwendet diese Funktion beispielsweise, um eine Verbindung mithilfe des Telefonbucheintrags herzustellen, der einer Remoteadresse zugeordnet ist.

Die RasDialDlg-Funktion zeigt während des Verbindungsvorgangs Dialogfelder an, um dem Benutzer Feedback zum Fortschritt des Vorgangs zu geben. Beispielsweise können die Dialogfelder angeben, wann der Vorgang wählt, wann die Anmeldeinformationen des Benutzers auf dem Remoteserver authentifiziert werden usw. Die Dialogfelder stellen auch eine Schaltfläche Abbrechen bereit, mit der der Benutzer den Vorgang beenden kann.

RasDialDlg gibt zurück, wenn die Verbindung hergestellt wird oder wenn der Benutzer den Vorgang abbricht.

Der folgende Beispielcode wählt den Eintrag im Standardtelefonbuch, das durch die Variable lpszEntry angegeben wird.

Hinweis Dieses einfache Beispiel soll unter Windows Vista und höheren Versionen von Windows ausgeführt werden. Beachten Sie, dass der Aufruf von sizeof(RASENTRY) je nachdem, welche Version des Betriebssystems der Code ausgeführt wird, einen anderen Wert zurückgibt. Führen Sie Schritte aus, um sicherzustellen, dass dies ordnungsgemäß behandelt wird.

#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;
}

Hinweis

Der rasdlg.h-Header definiert RasDialDlg als Alias, der die ANSI- oder Unicode-Version dieser Funktion basierend auf der Definition der UNICODE-Präprozessorkonstante automatisch auswählt. Das Mischen der Verwendung des codierungsneutralen Alias mit Code, der nicht Codierungsneutral ist, kann zu Nichtübereinstimmungen führen, die zu Kompilierungs- oder Laufzeitfehlern führen. Weitere Informationen finden Sie unter Konventionen für Funktionsprototypen.

Anforderungen

Anforderung	Wert
Unterstützte Mindestversion (Client)	Windows 2000 Professional [nur Desktop-Apps]
Unterstützte Mindestversion (Server)	Windows 2000 Server [nur Desktop-Apps]
Zielplattform	Windows
Kopfzeile	rasdlg.h
Bibliothek	Rasdlg.lib
DLL	Rasdlg.dll

Weitere Informationen

RASDIALDLG

RasPhonebookDlg

Übersicht über ras (Remote Access Service, RAS)

Funktionen des RAS-Diensts

Share via