mail::folder::renameFolder — Rename a folder
#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); |
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.
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.
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.
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.
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.
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.
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.
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).