RasEnumEntriesA function (ras.h)
The RasEnumEntries function lists all entry names in a remote access phone book.
Syntax
DWORD RasEnumEntriesA(
[in] LPCSTR unnamedParam1,
[in] LPCSTR unnamedParam2,
[in, out] LPRASENTRYNAMEA unnamedParam3,
[in, out] LPDWORD unnamedParam4,
[out] LPDWORD unnamedParam5
);
Parameters
[in] unnamedParam1
Reserved; must be NULL.
[in] unnamedParam2
Pointer to a null-terminated string that specifies the full path and file name of a phone-book (PBK) file. If this parameter is NULL, the function uses the current default phone-book file. The default phone-book file is the one selected by the user in the User Preferences property sheet of the Dial-Up Networking dialog box.
If this parameter is NULL, the entries are enumerated from all the remote access phone-book files in the AllUsers profile and the user's profile.
[in, out] unnamedParam3
Pointer to a buffer that, on output, receives an array of RASENTRYNAME structures, one for each phone-book entry.
On input, an application must set the dwSize member of the first RASENTRYNAME structure in the buffer to sizeof(RASENTRYNAME) in order to identify the version of the structure being passed.
[in, out] unnamedParam4
Pointer to a variable that, on input, contains the size, in bytes, of the buffer specified by lprasentryname.
Pointer to a variable that, on output, contains the size, in bytes, of the array of RASENTRYNAME structures required for the phone-book entries.
Windows Vista or later: To determine the required buffer size, call RasEnumEntries with lprasentryname set to NULL. The variable pointed to by lpcb should be set to zero. The function will return the required buffer size in lpcb and an error code of ERROR_BUFFER_TOO_SMALL.
[out] unnamedParam5
Pointer to a variable that receives to the number of phone-book entries written to the buffer specified by lprasentryname.
Return value
If the function succeeds, the return value is ERROR_SUCCESS.
If the function fails, the return value is one of the following error codes or a value from Routing and Remote Access Error Codes or Winerror.h.
| Value | Meaning |
|---|---|
|
The lprasentryname buffer is not large enough. The lpcb parameter is less than the dwSize member in the lprasentryname parameter which should be set prior to calling the function. The function returns the required buffer size in the variable pointed to by lpcb.
Windows Vista or later: The lprasentryname buffer may be set to NULL and the variable pointed to by lpcb may be set to zero. The function will return the required buffer size in the variable pointed to by lpcb. |
|
The value of dwSize in the RASENTRYNAME structure pointed to by lprasentryname, specifies a version of the structure that is not supported on the current platform. For example, on Windows 95, RasEnumEntries returns this error if dwSize indicates that RASENTRYNAME includes the dwFlags and szPhonebookPath members, since these members are not supported on Windows 95 (they are supported only on Windows 2000 and later). |
|
The function could not allocate sufficient memory to complete the operation. |
Remarks
The following sample code enumerates the RAS phone-book entries on Windows Vista and later versions of Windows. The code initially calls RasEnumEntries to obtain the size of the buffer to pass in. The code then calls RasEnumEntries again, to enumerate the entries. Note that for the second call, the code sets the dwSize member of the first RASENTRYNAME structure in the buffer to sizeof(RASENTRYNAME) to specify the structure version.
#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;
}
Note
The ras.h header defines RasEnumEntries as an alias that automatically selects the ANSI or Unicode version of this function based on the definition of the UNICODE preprocessor constant. Mixing usage of the encoding-neutral alias with code that is not encoding-neutral can lead to mismatches that result in compilation or runtime errors. For more information, see Conventions for Function Prototypes.
Requirements
| Requirement | Value |
|---|---|
| Minimum supported client | Windows 2000 Professional [desktop apps only] |
| Minimum supported server | Windows 2000 Server [desktop apps only] |
| Target Platform | Windows |
| Header | ras.h |
| Library | Rasapi32.lib |
| DLL | Rasapi32.dll |