RasEnumEntriesA 函式 (ras.h)

  • 發行項

RasEnumEntries 函式會列出遠端訪問電話簿中的所有項目名稱。

語法

DWORD RasEnumEntriesA(
  [in]      LPCSTR          unnamedParam1,
  [in]      LPCSTR          unnamedParam2,
  [in, out] LPRASENTRYNAMEA unnamedParam3,
  [in, out] LPDWORD         unnamedParam4,
  [out]     LPDWORD         unnamedParam5
);

參數

[in] unnamedParam1

保留;必須是 NULL。

[in] unnamedParam2

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

如果此參數為 NULL，則會從 AllUsers 設定檔和使用者配置檔中的所有遠端存取電話簿檔案列舉專案。

[in, out] unnamedParam3

緩衝區的指標，在輸出時會收到 RASENTRYNAME 結構的陣列，每個電話簿專案各一個。

在輸入時，應用程式必須將緩衝區中第一個RASENTRYNAME結構的 dwSize 成員設定為 sizeof (RASENTRYNAME) ，才能識別所傳遞的結構版本。

[in, out] unnamedParam4

在輸入時，變數的指標包含 lprasentryname 所指定緩衝區的大小，以位元組為單位。

輸出時，變數的指標包含電話簿專案所需 RASENTRYNAME 結構陣列的大小，以位元組為單位。

Windows Vista 或更新版本： 若要判斷所需的緩衝區大小，請使用 lprasentryname 設為 NULL 呼叫 RasEnumEntries。 l其所指向的變數應該設定為零。 函式會以 l ERROR_BUFFER_TOO_SMALL傳回所需的緩衝區大小。

[out] unnamedParam5

變數的指標，該變數會接收寫入 lprasentryname 所指定之緩衝區的電話簿項目數目。

傳回值

如果函式成功，傳回值會 ERROR_SUCCESS。

如果函式失敗，則傳回值是下列其中一個錯誤碼，或 來自路由和遠端訪問錯誤碼 或 Winerror.h 的值。

值 意義
ERROR_BUFFER_TOO_SMALL
 lprasentryname 緩衝區不夠大。 l 參數小於 lprasentryname 參數中的 dwSize 成員，在呼叫 函式之前應該設定。 函式會傳回 l其所指向之變數中所需的緩衝區大小。

Windows Vista 或更新版本： lprasentryname 緩衝區可能設定為 NULL，而 l其指向的變數可能設定為零。 函式會傳回 l其所指向之變數中所需的緩衝區大小。
ERROR_INVALID_SIZE
 lprasentryname 所指向 RASENTRYNAME 結構中的 dwSize 值，指定目前平臺上不支援的結構版本。 例如，在 Windows 95 上，如果 dwSize 指出 RASENTRYNAME 包含 dwFlags 和 szPhonebookPath 成員，RasEnumEntries 會傳回此錯誤，因為這些成員在 Windows 95 上不受支援， (只有 Windows 2000 和更新版本) 。
ERROR_NOT_ENOUGH_MEMORY
 函式無法配置足夠的記憶體來完成作業。

備註

下列範例程式代碼會列舉 Windows Vista 和更新版本的 Windows 上的 RAS 電話簿專案。 程式代碼一開始會呼叫 RasEnumEntries ，以取得要傳入的緩衝區大小。 程式代碼接著會再次呼叫 RasEnumEntries ，以列舉專案。 請注意，針對第二次呼叫，程式代碼會將緩衝區中第一個RASENTRYNAME結構的 dwSize 成員設定為sizeof (RASENTRYNAME) 來指定結構版本。

#include <windows.h>
#include <stdio.h>
#include "ras.h"
#include "raserror.h"
#pragma comment(lib, "rasapi32.lib")

DWORD __cdecl wmain(){

    DWORD dwCb = 0;
    DWORD dwRet = ERROR_SUCCESS;
    DWORD dwEntries = 0;
    LPRASENTRYNAME lpRasEntryName = NULL;
    
    // Call RasEnumEntries with lpRasEntryName = NULL. dwCb is returned with the required buffer size and 
    // a return code of ERROR_BUFFER_TOO_SMALL
    dwRet = RasEnumEntries(NULL, NULL, lpRasEntryName, &dwCb, &dwEntries);

    if (dwRet == ERROR_BUFFER_TOO_SMALL){
        // Allocate the memory needed for the array of RAS entry names.
        lpRasEntryName = (LPRASENTRYNAME) HeapAlloc(GetProcessHeap(), HEAP_ZERO_MEMORY, dwCb);
        if (lpRasEntryName == NULL){
            wprintf(L"HeapAlloc failed!\n");
            return 0;
        }
        // The first RASENTRYNAME structure in the array must contain the structure size
        lpRasEntryName[0].dwSize = sizeof(RASENTRYNAME);
        
        // Call RasEnumEntries to enumerate all RAS entry names
        dwRet = RasEnumEntries(NULL, NULL, lpRasEntryName, &dwCb, &dwEntries);

        // If successful, print the RAS entry names 
        if (ERROR_SUCCESS == dwRet){
            wprintf(L"The following RAS entry names were found:\n");
            for (DWORD i = 0; i < dwEntries; i++){
                wprintf(L"%s\n", lpRasEntryName[i].szEntryName);
            }
        }
        //Deallocate memory for the connection buffer
        HeapFree(GetProcessHeap(), 0, lpRasEntryName);
        lpRasEntryName = NULL;
        return 0;
    }

    // There was either a problem with RAS or there are RAS entry names to enumerate    
    if(dwEntries >= 1){
        wprintf(L"The operation failed to acquire the buffer size.\n");
    }else{
        wprintf(L"There were no RAS entry names found:.\n");
    }

    return 0;
}

注意

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

規格需求

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

另請參閱

RASENTRYNAME

RasEnumConnections

遠端訪問服務 (RAS) 概觀

遠端存取服務函式