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 成员设置为 size (RASENTRYNAME) ，以便标识所传递结构的版本。
[in, out] unnamedParam4
指向变量的指针，该变量在输入时包含 由 lprasentryname 指定的缓冲区的大小（以字节为单位）。
指向变量的指针，该变量在输出时包含电话簿条目所需的 RASENTRYNAME 结构数组的大小（以字节为单位）。
Windows Vista 或更高版本： 若要确定所需的缓冲区大小，请调用将 lprasentryname 设置为 NULL 的 RasEnumEntries。 l所指向的变量应设置为零。 该函数将以 l ERROR_BUFFER_TOO_SMALL 返回所需的缓冲区大小和错误代码。
[out] unnamedParam5
指向变量的指针，该变量接收写入 到 lprasentryname 指定的缓冲区的电话簿条目数。
返回值
如果函数成功，则返回值 ERROR_SUCCESS。
如果函数失败，则返回值为以下错误代码之一，或者来自 路由和远程访问错误代码 或 Winerror.h 的值。
| 值 | 含义 |
|---|---|
|
lprasentryname 缓冲区不够大。 l 参数小于 lprasentryname 参数中的 dwSize 成员，应在调用函数之前设置该成员。 该函数在 l 指向的变量中返回所需的缓冲区大小。
Windows Vista 或更高版本： lprasentryname 缓冲区可以设置为 NULL，l指向的变量可以设置为零。 该函数将在 l 指向的变量中返回所需的缓冲区大小。 |
|
lprasentryname 指向的 RASENTRYNAME 结构中的 dwSize 值指定当前平台上不支持的结构版本。 例如，在 Windows 95 上，如果 dwSize 指示 RASENTRYNAME 包括 dwFlags 和 szPhonebookPath 成员，RasEnumEntries 将返回此错误，因为这些成员在 Windows 95 上不受支持 (它们仅在 Windows 2000 及更高版本) 上受支持。 |
|
函数无法分配足够的内存来完成操作。 |
注解
以下示例代码枚举 Windows Vista 和更高版本的 Windows 上的 RAS 电话簿条目。 代码最初调用 RasEnumEntries 以获取要传入的缓冲区的大小。 然后，代码再次调用 RasEnumEntries 以枚举条目。 请注意，对于第二次调用，代码将缓冲区中第一个 RASENTRYNAME 结构的 dwSize 成员设置为 size of (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 |
| Library | Rasapi32.lib |
| DLL | Rasapi32.dll |