mail::ACCOUNT::renameFolder.3x man page
mail::ACCOUNT::renameFolder — Rename a folder
#include <libmail/sync.H> mail::ACCOUNT *mail;
mail::folder *folder=mail->renameFolder(const mail::folder *oldFolder, const mail::folder *newParent, std::string name);
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.
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.
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.
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.