RasEntryDlgA 函式 (rasdlg.h)

發行項
03/01/2024

RasEntryDlg 函式會顯示強制響應屬性表，允許使用者操作電話簿專案。如果編輯或複製現有的電話簿專案，函式會顯示電話簿專案屬性表。當使用者關閉屬性表時， RasEntryDlg 函式會傳回。

語法

BOOL RasEntryDlgA(
  [in] LPSTR          lpszPhonebook,
  [in] LPSTR          lpszEntry,
  [in] LPRASENTRYDLGA lpInfo
);

參數

[in] lpszPhonebook

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

[in] lpszEntry

Null 終止字串的指標，指定要編輯、複製或建立之電話簿項目的名稱。

如果您要編輯或複製專案，此參數是現有電話簿項目的名稱。如果您要複製專案，請在RASENTRYDLG結構的 dwFlags 成員中設定RASEDFLAG_CloneEntry旗標。

注意自 Windows Vista 和 Windows Server 2008 起， RASEDFLAG_CloneEntry 旗標已被取代。它在後續版本中可能會變更或無法使用。相反地，呼叫 RasGetEntryProperties 以取得專案，然後呼叫 RasSetEntryProperties 以儲存具有新名稱的專案來複製專案。

如果您要建立專案，此參數是用戶可變更的預設新項目名稱。如果此參數為 NULL，函式會提供預設名稱。如果您要建立專案，請在RASENTRYDLG結構的 dwFlags 成員中設定RASEDFLAG_NewEntry旗標。

[in] lpInfo

指定其他輸入和輸出參數之 RASENTRYDLG 結構的指標。這個結構的 dwSize 成員必須指定 sizeof (RASENTRYDLG) 。使用 dwFlags 成員來指出您要建立、編輯或複製專案。如果發生錯誤， dwError 成員會傳回錯誤碼;否則會傳回零。

傳回值

如果使用者建立、複製或編輯電話簿專案，則傳回值為 TRUE。否則，函式會傳回 FALSE。

如果發生錯誤，RasEntryDlg 會將RASENTRYDLG結構的 dwError 成員設定為路由和遠端訪問錯誤碼或Winerror.h的值。

備註

RasCreatePhonebookEntry 和 RasEditPhonebookEntry 函式會呼叫 RasEntryDlg 函式。

下列範例程式代碼會顯示屬性表來建立新專案。 lpszEntry 變數會指定新項目的預設名稱。

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

DWORD __cdecl wmain(){

    DWORD dwRet = ERROR_SUCCESS;
    BOOL nRet = TRUE;
    LPTSTR lpszEntry = L"EntryName";

    // Allocate heap memory and initialize RASENTRYDLG structure
    LPRASENTRYDLG lpEntry = (LPRASENTRYDLG)HeapAlloc(GetProcessHeap(), HEAP_ZERO_MEMORY, sizeof(RASENTRYDLG));
    if (lpEntry == NULL){
        wprintf(L"HeapAlloc failed.\n");
        return 0;
    }
    
    // The RASENTRYDLG->dwSize member has to be initialized or the RRAS APIs will fail below.
    lpEntry->dwSize = sizeof(RASENTRYDLG);
    lpEntry->dwFlags |= RASEDFLAG_NewEntry;

    // Create the new entry using a user dialog
    nRet = RasEntryDlg(NULL, lpszEntry, lpEntry);

    // Any error codes are returned in lpEntry
    dwRet = lpEntry->dwError;
    
    if (nRet == TRUE) {
        wprintf(L"New entry created: %s\n", lpEntry->szEntry);

        // Clean up: delete the new entry
        dwRet = RasDeleteEntry(NULL, lpszEntry);
        if (dwRet != ERROR_SUCCESS) {
            wprintf(L"RasDeleteEntry failed: Error = %d\n", dwRet);
        }

    } 
    else {
        if (dwRet != ERROR_SUCCESS) {
            wprintf(L"RasEntryDlg failed: Error = %d\n", dwRet);
        }
        else {
            wprintf(L"User pressed Cancel\n");
        }
    }

    HeapFree(GetProcessHeap(), 0, lpEntry);
    return 0;
}

注意

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

規格需求

需求	值
最低支援的用戶端	Windows 2000 Professional [僅限傳統型應用程式]
最低支援的伺服器	Windows 2000 Server [僅限桌面應用程式]
目標平台	Windows
標頭	rasdlg.h
程式庫	Rasdlg.lib
Dll	Rasdlg.dll