RasEnumEntries

The RasEnumEntries function lists all entry names in a remote access phone book.

DWORD RasEnumEntries (
  LPCTSTR reserved,               // reserved, must be NULL
  LPTCSTR lpszPhonebook,          // pointer to full path and
                                  //  file name of phone-book file
  LPRASENTRYNAME lprasentryname,  // buffer to receive
                                  //  phone-book entries
  LPDWORD lpcb,                   // size in bytes of buffer
  LPDWORD lpcEntries              // number of entries written
                                  //  to buffer
);

Parameters

reserved

Reserved; must be NULL.

lpszPhonebook

Windows NT/2000: 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.

Windows 2000: If this paramter is NULL, the entries are enumerated from all the remote access phone-book files in the AllUsers profile and the user's profile.

Windows 95: This parameter is ignored. Dial-up networking stores phone-book entries in the registry rather than in a phone-book file.

lprasentryname

Pointer to a buffer that receives an array of RASENTRYNAME structures, one for each phone-book entry. Before calling the function, 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.

lpcb

Pointer to a variable that contains the size, in bytes, of the buffer specified by lprasentryname. On return, the function sets this variable to the number of bytes required to successfully complete the call.

lpcEntries

Pointer to a variable that the function, if successful, sets to the number of phone-book entries written to the buffer specified by lprasentryname.

Return Values

If the function succeeds, the return value is zero.

If the function fails, the return value is a nonzero error value listed in the RAS header file or one of the following values.

Remarks

The following sample code enumerates the RAS phone-book entries on the current machine. 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 both calls, the code sets the dwSize member of the first RASENTRY structure in the buffer to sizeof(RASENTRY) to specify the structure version.

lpRasEntryName = (LPRASENTRYNAME)GlobalAlloc(GPTR, sizeof(RASENTRYNAME));
lpRasEntryName->dwSize = sizeof(RASENTRYNAME);
if ((nRet = RasEnumEntries(NULL, NULL, lpRasEntryName, &cb, &cEntries)) 
    == ERROR_BUFFER_TOO_SMALL)
{
    lpRasEntryName = (LPRASENTRYNAME)GlobalAlloc(GPTR, cb);
    lpRasEntryName->dwSize = sizeof(RASENTRYNAME);
}
 
// Calling RasEnumEntries to enumerate the phone-book entries    
nRet = RasEnumEntries(NULL, NULL, lpRasEntryName, &cb, &cEntries);
 
if (nRet != ERROR_SUCCESS)
{
    printf("RasEnumEntries failed: Error %d\n", nRet);
}
else
{
    printf("Phone-book entries in the default phone book:\n\n");
    for(i=0;i < cEntries;i++)
    {
        printf("%s\n",lpRasEntryName->szEntryName);
        lpRasEntryName++;
    }
}

Requirements

  Windows NT/2000: Requires Windows NT 3.1 or later.
  Windows 95/98: Requires Windows 95 or later.
  Header: Declared in Ras.h.
  Library: Use Rasapi32.lib.
  Unicode: Implemented as Unicode and ANSI versions on Windows NT/2000.

See Also

Remote Access Service (RAS) Overview, Remote Access Service Functions, RASENTRYNAME, RasEnumConnections