mail::folder::renameFolder
Prev | mail::folder Native API reference | Next

## 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::folders are linked to their corresponding mail::accounts. A mail::folder created by one mail::account may not be used with a different mail::folder. All mail::folders 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::folders, 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).

Prev | Up | Next
mail::folder::readSubFolders | Home | ToC | mail::folder::setRights