RasDialDlgA 函式 （rasdlg.h）

RasDialDlg 函式會使用指定的電話簿專案和登入使用者的認證來建立 RAS 連線。 函式會顯示對話框數據流，指出連接作業的狀態。

語法

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

參數

[in] lpszPhonebook

Null 終止字串的指標，指定電話簿檔案的完整路徑和檔名。 如果此參數 NULL，則函式會使用目前的預設電話簿檔案。 默認的電話簿檔案是使用者在 [撥號網络] 對話框中 [使用者 喜好設定] 屬性表中選取的默認電話簿檔案。

[in] lpszEntry

Null 終止字串的指標，指定要撥打的電話簿項目名稱。

[in] lpszPhoneNumber

Null 終止字串的指標，指定會覆寫電話簿專案中所儲存號碼的電話號碼。 如果此參數 NULL，RasDialDlg 會使用電話簿專案中的數位。

[in] lpInfo

指定其他輸入和輸出參數之 RASDIALDLG 結構的指標。 這個結構的 dwSize 成員必須指定 sizeof（RASDIALDLG）。 如果發生錯誤，dwError 成員會傳回錯誤碼;否則，它會傳回零。

傳回值

如果函式建立 RAS 連線，則傳回值會 TRUE。 否則，函式應該 FALSE傳回 。

如果發生錯誤，RasDialDlg 應該將 RASDIALDLG 結構的 dwError 成員設定為 Routing and Remote Access Error Code 或 Winerror.h 的值。

言論

RasDialDlg 函式會顯示一系列對話框，類似於用戶選取 [Dial] 按鈕時，主要 撥號網络 對話框顯示的對話方塊。 使用 RasDialDlg 函式來顯示連線作業的標準使用者介面，而不顯示主要電話簿對話方塊。 例如，RAS 自動串行化服務會使用此函式，使用與遠端位址相關聯的電話簿專案建立連線。

RasDialDlg 函式會在連線作業期間顯示對話框，向使用者提供有關作業進度的意見反應。 例如，對話框可能會指出作業何時撥號、在遠端伺服器上驗證使用者的認證時等等。 對話框也會提供 取消 按鈕，讓使用者終止作業。

RasDialDlg 建立連線或使用者取消作業時傳回。

下列範例程式代碼會撥入變數所指定的默認電話簿中，lpszEntry。

附註 這個簡單的範例是要在 Windows Vista 和更新版本的 Windows 上執行。 請注意，sizeof（RASENTRY） 的呼叫會根據執行程式碼的作業系統版本傳回不同的值。 請採取步驟，以確保已適當地處理此情況。

 

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

注意

rasdlg.h 標頭會將 RasDialDlg 定義為別名，根據 UNICODE 預處理器常數的定義，自動選取此函式的 ANSI 或 Unicode 版本。 混合使用編碼中性別名與非編碼中性的程序代碼，可能會導致編譯或運行時間錯誤不符。 如需詳細資訊，請參閱函式原型的 慣例。

要求

要求	價值
最低支援的用戶端	Windows 2000 Professional [僅限傳統型應用程式]
支援的最低伺服器	Windows 2000 Server [僅限傳統型應用程式]
目標平臺	窗戶
標頭	rasdlg.h
連結庫	Rasdlg.lib
DLL	Rasdlg.dll

另請參閱

RASDIALDLG

RasPhonebookDlg

遠端存取服務 （RAS） 概觀

遠端訪問服務函式