<<< Previous |  | Next >>>

# mail::ACCOUNT::renameFolder

## Name

mail::ACCOUNT::renameFolder -- Rename a folder

## Synopsis

#include <libmail/sync.H>
mail::ACCOUNT *mail;

``mail::folder *folder=mail->`renameFolder``(const mail::folder *`oldFolder`, const mail::folder *`newParent`, std::string `name`);`

std::string errmsg=mail->getErrmsg();

## USAGE

This function renames an existing folder. `oldFolder` is an existing folder or a folder directory (see mail::folder::createSubFolder(3x) for more information on folders and folder directories). `newParent`, if not NULL, specifies the new parent folder directory. A NULL `newParent` specifies that the folder should be be moved to the top level of the mail account's folder hierarchy.

`name` specifies the new name of the folder, in the application's character set.

NOTE:

Some mail servers reserve certain characters which cannot be used in folder names. IMAP mail servers use a special character (usually "`/`" or "`.`") as a separator between names in a hierarchical folder path. The actual character varies from server to server. An attempt to create/rename a folder whose name includes a reserved character will fail. Different IMAP servers use different hierarchy separator characters. An attempt to create a folder may fail on one IMAP server even if another IMAP server can succesfully create a folder with the same name. This is, unfortunately, a design flaw in the IMAP protocol.

NOTE:

Maildir folders created by are compatible and can be read by the Courier-IMAP server. Names of maildir folders may contain any character, including the characters "`:`", "`/`", "`.`", "`~`", and "`:`". However, if the same folders are exported via IMAP, folders whose name includes these characters may not be readable by some IMAP clients. Even a `LibMAIL` application may not be able to read one of these folders via IMAP.

NOTE:

Mbox mail folders created by `LibMAIL` are mostly compatible and can be exported by IMAP servers that read mbox-formatted mail folders (with some limitations, such as that the same mbox folder cannot be open by `LibMAIL` and another application at the same time). Names of mbox folders can contain any character, including the characters "`/`", and "`~`". However if mbox folders are exported via IMAP, folders whose name includes these characters may not be readable by some IMAP clients.

## RETURN CODES AND CALLBACKS

This function returns a pointer to the renamed `mail::folder` object, or a NULL pointer if the folder cannot be renamed for some reason. The application is responsible for destroying the new `mail::folder` object, when it is no longer needed.

## SEE ALSO

mail::ACCOUNT::createFolder(3x).

<<< Previous | Home | Next >>>
mail::ACCOUNT::removeMessages | Up | mail::ACCOUNT::saveFolderIndexInfo