RasRenameEntryA function (ras.h)

The RasRenameEntry function changes the name of an entry in a phone book.


DWORD RasRenameEntryA(



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 Me/98/95:  This parameter should always be NULL. Dial-up networking stores phone-book entries in the registry rather than in a phone-book file.


Pointer to a null-terminated string that specifies an existing entry name.


Pointer to a null-terminated string that specifies the new entry name. Before calling RasRenameEntry, call the RasValidateEntryName function to validate the new entry name.

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 function could not allocate sufficient memory to complete the operation.
The lpszNewEntry name is invalid.
An entry with the lpszNewEntry name already exists.
The phone-book entry does not exist.


The RasRenameEntry function allows entry names that would not be accepted by the dial-up networking user interface. The entry names specified in RasRenameEntry can consist of any string that adheres to the following conditions:

  1. The string cannot have a length greater than RAS_MaxEntryName (as defined in Ras.h).
  2. The string cannot consist entirely of space or tab characters.
  3. The first character in the string cannot be a period character (".").
The following code sample renames the phone-book entry with the name specified by pszOldName to the new name specified by pszNewName.
#include <windows.h>
#include <stdio.h>
#include "ras.h"
#include <tchar.h>

DWORD main (){

    LPCTSTR pszOldName = L"RAS Connection 1\0";
    LPCTSTR pszNewName = L"RAS Connection 2\0";

    dwErr = RasValidateEntryName(NULL, pszNewName);
    if (ERROR_SUCCESS != dwErr)
        printf("RasValidateEntryName failed: Error = %d\n", dwErr);
        return dwErr;

    dwErr = RasRenameEntry(NULL, pszOldName, pszNewName);
    if (ERROR_SUCCESS != dwErr)
        printf("RasRenameEntry failed: Error = %d\n", dwErr);
        return dwErr;

    printf("Successfully renamed entry '%s' to '%s'\n", pszOldName, pszNewName);

    return 0;


The ras.h header defines RasRenameEntry as an alias which 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 not encoding-neutral can lead to mismatches that result in compilation or runtime errors. For more information, see Conventions for Function Prototypes.


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

See also


Remote Access Service (RAS) Overview

Remote Access Service Functions