RasDialDlgA 函式 (rasdlg.h)

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

語法

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

參數

[in] lpszPhonebook

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

[in] lpszEntry

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

[in] lpszPhoneNumber

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

[in] lpInfo

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

傳回值

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

如果發生錯誤，RasDialDlg 應該將 RASDIALDLG 結構的 dwError 成員設定為路由和遠端存取錯誤碼或 Winerror.h 的值。

備註

RasDialDlg 函式會顯示一系列的對話框，與用戶選取 [撥號] 按鈕時，主 [撥號網络] 對話框顯示的對話框類似。 使用 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 專業版 [僅限傳統型應用程式]
最低支援的伺服器	Windows 2000 Server [僅限傳統型應用程式]
目標平台	Windows
標頭	rasdlg.h
程式庫	Rasdlg.lib
Dll	Rasdlg.dll

另請參閱

RASDIALDLG

RasPhonebookDlg

遠端訪問服務 (RAS) 概觀

遠端存取服務函式