IProfAdmin::RenameProfile

Platform SDK: MAPI

IProfAdmin::RenameProfile

The IProfAdmin::RenameProfile method assigns a new name to a profile.

Quick Info

HRESULT RenameProfile(
  LPTSTR lpszOldProfileName,   
  LPTSTR lpszOldPassword,   
  LPTSTR lpszNewProfileName,   
  ULONG ulUIParam,          
  ULONG ulFlags             
);

Parameters

lpszOldProfileName

[in] Pointer to the current name of the profile to rename.

lpszOldPassword

[in] Pointer to the password of the profile to rename or NULL, indicating that the profile does not require a password. However, if lpszOldPassword is set to NULL and the profile does require a password, RenameProfile displays a dialog box if possible to prompt the user.

lpszNewProfileName

[in] Pointer to the new name of the profile to rename.

ulUIParam

[in] Handle of the parent window for any dialog boxes or windows this method displays.

ulFlags

[in] Bitmask of flags that controls how the renaming operation is performed. The following flags can be set:

MAPI_DIALOG: Allows the display of a dialog box prompting the user for the profile's password. If this flag is not set, no dialog box is displayed.
MAPI_UNICODE: The profile names and password are in Unicode format. If the MAPI_UNICODE flag is not set, these strings are in ANSI format.

Return Values

S_OK: The profile was successfully renamed.
MAPI_E_LOGON_FAILED: The profile password is incorrect.
MAPI_E_USER_CANCEL: The user canceled the operation, typically by clicking the Cancel button in a dialog box.

Remarks

The IProfAdmin::RenameProfile method assigns a new name to a profile without changing its password, if it has one. If the profile to rename is in use by a client when RenameProfile is called, RenameProfile marks the profile and returns S_OK rather than attempting the rename operation while the profile is in use. When the profile is no longer being used, RenameProfile assigns it the new name.

The old and new names of the profile and the password can be up to 64 characters in length and can include the following characters:

All alphanumeric characters, including accent characters and the underscore character.
Embedded spaces, but not leading or trailing spaces.

Profile passwords are not supported on all operating system platforms; on platforms that do not support profile passwords, lpszPassword can be NULL or a pointer to a zero-length string. Currently, Windows NT Server and Windows 95 do not support passwords; Windows version 3.1 does.

The MAPI_DIALOG flag must be set in order for RenameProfile to display a user interface. If a client passes NULL in lpszOldPassword and the target profile requires a password, a dialog box must be displayed to allow the user to supply the missing password. If MAPI_DIALOG is not set in this situation, RenameProfile returns MAPI_E_LOGON_FAILED.