RasEnumEntries

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)