RasRenameEntry

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

DWORD RasRenameEntry(
  LPCTSTR lpszPhonebook, // pointer to full path and file name of 
                         //  phone-book file
  LPCTSTR lpszOldEntry,  // pointer to the old entry name
  LPCTSTR lpszNewEntry   // pointer to the new entry name
);

Parameters

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

lpszOldEntry

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

lpszNewEntry

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

Return Values

If the function succeeds, the return value is zero.

If the function fails, the return value is one of the following error codes.

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

The following code sample renames the phone-book entry with the name specified by lpszOldEntry to the new name specified by lpszNewEntry.

nRet = RasRenameEntry(NULL, lpszOldEntry, lpszNewEntry);

Requirements

  Windows NT/2000: Requires Windows NT 4.0 or later.
  Windows 95/98: Requires Windows 95 OSR2 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, RasValidateEntryName