<<< Previous |  | Next >>>

# mail::folder::renameFolder

## Name

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

## Synopsis

#include <libmail/mail.H>
class myCallback : public mail::callback {
public:
void success(std::string msg);
void fail(std::string msg);
};

class myFolderCallback : public mail::callback::folderlist {
public:
void success(const std::vector<const mail::folder *> &folders);
};

mail::folder *folder;

``folder->`renameFolder``(const mail::folder *`newParent`, std::string `name`, myFolderCallback &`folderCallback`, myCallback &`callback`);`

## USAGE

This function renames an existing folder. `folder` 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

The application must wait until `callback`'s `success` or `fail` method is invoked. The `success` method is invoked when this request is succesfully processed. The `fail` method is invoked if this request cannot be processed. The application must not destroy `callback` until either the `success` or `fail` method is invoked.

NOTE: | `callback`'s `fail` method may be invoked even after other callback methods were invoked. This indicates that the request was partially completed before the error was encountered.

NOTE: | The application must not destroy `folderCallback` until this request fails or succeeds. `folderCallback`'s `success` method is invoked just before the `callback`'s `success` method.

If the folder was succesfully renamed, the `folderCallback.success` method receives a vector that contains a single pointer to a `mail::folder` object that refers to this folder under its new name. The existing `mail::folder` object is no longer valid, and should be destroyed. The new `mail::folder` object should now be used to refer to this folder.

NOTE: | `mail::folder`s are linked to their corresponding `mail::account`s. A `mail::folder` created by one `mail::account` may not be used with a different `mail::folder`. All `mail::folder`s created by a `mail::account` are invalidated when this `mail::account` object is destroyed. Note that the `mail::folder` objects are not automatically destroyed; the application is still responsible for destroying any remaining `mail::folder`s, after their a `mail::account` is destroyed.

NOTE: | The `folderCallback.success` method receives a (possibly empty) vector of pointers to `mail::folder` objects. These objects will be destroyed when `folderCallback.success` terminates. The application must use mail::folder::clone(3x) to create copies of `mail::folder` objects it wants to use later.

NOTE: | Both `folderCallback.success` and `myCallback.success` method will be invoked if this request succeeds. `folderCallback.success` will be invoked before `myCallback.success` (since by definition this indicates that the request has been completed).

## SEE ALSO

mail::folder::clone(3x), mail::folder::create(3x), mail::folder::createSubFolder(3x), mail::folder::destroy(3x), mail::folder::readSubFolders(3x).

<<< Previous | Home | Next >>>
mail::folder::readSubFolders | Up | mail::folder::setRights