DWORD RasEnumEntries(
_In_ LPCTSTR reserved,
_In_ LPCTSTR lpszPhonebook,
_Inout_ LPRASENTRYNAME lprasentryname,
_Inout_ LPDWORD lpcb,
_Out_ LPDWORD lpcEntries
);
说明
枚举所有远程访问电话簿中的条目。
参数
reserved [in]
保留,必须为NULL。
lpszPhonebook [in]
指向一个包含完整路径的电话簿文件(PBK)。如果参数为空,则该函数使用默认的电话簿文件。默认的电话簿文件由用户在拨号网络对话框的[user preferences]属性窗口中选择。
lprasentryname [in, out]
指向RASENTRYNAME结构的数组指针,每个结构存储一个条目。
调用前需要将第一个结构的dwSize成员设置为sizeof(RASENTRYNAME)。
lpcb [in, out]
作为输入,指向一个存储lprasentryname缓冲字节数的变量。
作为输出,用于获取存储所有条目需要的字节数。
Windows Vista及以后版本:将lprasentryname设置为NULL时可通过该函数获取存储所有条目需要的缓冲字节数,存储在lpcb指向的变量中返回。调用前需要将lpcb指向的变量设置为0,同时该函数将返回ERROR_BUFFER_TOO_SMALL错误码。
lpcEntries [out]
用于接收写入到lprasentryname指向的缓冲的条目数量。
返回值
成功时返回ERROR_SUCCESS。
失败时返回下列表格中的错误之一,或者是来自Routing and Remote Access Error Codes或Winerror.h中定义的错误码。
值 | 含义 |
---|---|
ERROR_BUFFER_TOO_SMALL | lprasentryname参数指向的缓冲长度不足。如何获取需要的缓冲长度请参照lpcb参数的说明。 |
ERROR_INVALID_SIZE | 根据RASENTRYNAME结构的dwSize的值识别出当前平台不支持该版本的结构。比如结构中的dwFlags和szPhonebookPath两个成员只能在Windows 2000及以后的版本中才能使用。如果dwSize的值包含了这两个成员,则该函数会返回此错误。 |
ERROR_NOT_ENOUGH_MEMORY | 无法分配足够的内存来完成操作。 |
注意事项
以下示例代码运行于Windows Vista及以后的版本,用于枚举所有RAS电话簿条目。
#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;
}
系统支持
客户端最小支持 | Windows 2000专业版 |
---|---|
服务端最小支持 | Windows 2000 Server |
Header | Ras.h |
Lirbary | Rasapi32.lib |
DLL | Rasapi32.dll |
Unicode和ANSI名称 | RasEnumEntriesW(Unicode)和RasEnumEntriesA(ANSI) |