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 終止字串的指標，指定電話簿檔案的完整路徑和檔名。 如果此參數 NULL，則函式會使用目前的預設電話簿檔案。 默認的電話簿檔案是使用者在 [撥號網络] 對話框中 [使用者 喜好設定] 屬性表中選取的默認電話簿檔案。
如果此參數 NULL，則會從 AllUsers 設定檔和使用者設定檔中的所有遠端存取電話簿檔案列舉專案。
[in, out] unnamedParam3
輸出時，緩衝區的指標會接收 RASENTRYNAME 結構的陣列，每個電話簿專案各一個。
在輸入時，應用程式必須將緩衝區中第一個 RASENTRYNAME 結構 dwSize 成員設定為 sizeof（RASENTRYNAME），才能識別所傳遞結構的版本。
[in, out] unnamedParam4
在輸入時，變數的指標包含由 lprasentryname所指定的緩衝區大小，以位元組為單位。
輸出中變數的指標包含電話簿專案所需的 RASENTRY NAME 陣列大小，以位元組為單位。
[out] unnamedParam5
變數的指標，該變數會接收寫入 lprasentryname 所指定之緩衝區的電話號碼。
傳回值
如果函式成功，則傳回值會 ERROR_SUCCESS。
如果函式失敗，傳回值是下列其中一個錯誤碼，或來自 路由和遠端訪問錯誤碼的值 或 Winerror.h。
| 價值 | 意義 |
|---|---|
|
lprasentryname 緩衝區不夠大。
l 參數小於呼叫函式之前，lprasentryname 參數中 dwSize 成員。 函式會傳回 l所指向之變數中所需的緩衝區大小。
Windows Vista 或更新版本：lprasentryname 緩衝區可能設定為 NULL，而 l l 指向的變數可能設定為零。 函式會傳回 l所指向之變數中所需的緩衝區大小。 |
|
RASENTRYNAME 結構中 dwSize 的值，lprasentryname所指向，指定目前平臺上不支持的結構版本。 例如， 在 Windows 95 上，RasEnumEntries 如果 dwSize 表示 RASENTRYNAME 包含 dwFlags 和 szPhonebookPath 成員，因為這些成員在 Windows 95 上不受支援，所以會傳回此錯誤（只有在 Windows 2000 和更新版本上才支援這些成員）。 |
|
函式無法配置足夠的記憶體來完成作業。 |
言論
下列範例程式代碼會列舉 Windows Vista 和更新版本的 Windows 上的 RAS 電話簿專案。 程式代碼一開始會呼叫 RasEnumEntries，以取得要傳入的緩衝區大小。 然後，程式代碼會再次呼叫 RasEnumEnt ries，以列舉專案。 請注意，在第二次呼叫中，程式代碼會將緩衝區中第一個
#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 標頭會根據 UNICODE 預處理器常數的定義，將 RasEnumEntries 定義為自動選取此函式的 ANSI 或 Unicode 版本。 混合使用編碼中性別名與非編碼中性的程序代碼，可能會導致編譯或運行時間錯誤不符。 如需詳細資訊，請參閱函式原型的
要求
| 要求 | 價值 |
|---|---|
| 最低支援的用戶端 | Windows 2000 Professional [僅限傳統型應用程式] |
| 支援的最低伺服器 | Windows 2000 Server [僅限傳統型應用程式] |
| 目標平臺 | 窗戶 |
| 標頭 | ras.h |
| 連結庫 | Rasapi32.lib |
| DLL | Rasapi32.dll |