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指定的缓冲区的大小（以字节为单位）。
指向一个变量的指针，该变量包含电话簿条目所需的 RASENTRY NAME 数组的大小（以字节为单位）。
Windows Vista 或更高版本：若要确定所需的缓冲区大小，请调用 RasEnumEntries，lprasentryname 设置为 NULL。 l 指向的变量应设置为零。 该函数将返回 l 中所需的缓冲区大小，并返回 ERROR_BUFFER_TOO_SMALL的错误代码。
[out] unnamedParam5
指向一个变量的指针，该变量接收写入到 lprasentryname指定的缓冲区的电话簿条目数。
返回值
如果函数成功，则返回值 ERROR_SUCCESS。
如果函数失败，则返回值是以下错误代码之一或来自 路由和远程访问错误代码 或 Winerror.h 的值。
| 价值 | 意义 |
|---|---|
|
lprasentryname 缓冲区不够大。
l 参数小于 lprasentryname 参数中的 dwSize 成员，该参数应在调用函数之前设置。 该函数返回 l指向的变量中所需的缓冲区大小。
Windows Vista 或更高版本：lprasentryname 缓冲区可能设置为 NULL，l 指向的变量可能设置为零。 该函数将返回 l指向的变量中所需的缓冲区大小。 |
|
RASENTRYNAME 结构中 dwSize 的值由 lprasentryname指向，指定当前平台上不支持的结构版本。 例如， 在 Windows 95 上，RasEnumEntries 如果 dwSize 指示 RASENTRYNAME 包括 dwFlags 和 szPhonebookPath 成员，因为这些成员在 Windows 95 上不受支持（它们仅在 Windows 2000 及更高版本上受支持）。 |
|
该函数无法分配足够的内存来完成操作。 |
言论
以下示例代码枚举 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 [仅限桌面应用] |
| 目标平台 | 窗户 |
| 标头 | ras.h |
| 库 | Rasapi32.lib |
| DLL | Rasapi32.dll |