RasRenameEntryA function (ras.h)

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

Syntax

DWORD RasRenameEntryA(
  [in] LPCSTR unnamedParam1,
  [in] LPCSTR unnamedParam2,
  [in] LPCSTR unnamedParam3
);

Parameters

[in] unnamedParam1

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.

[in] unnamedParam2

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

[in] unnamedParam3

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.

Remarks

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 (".").

#include <windows.h>
#include <stdio.h>
#include "ras.h"
#include <tchar.h>

DWORD main (){

    DWORD dwErr = ERROR_SUCCESS;
    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;
}

Requirements

See also

RasValidateEntryName

Remote Access Service (RAS) Overview

Remote Access Service Functions