mail::account::readTopLevelFolders — Enumerate top-level folders
#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::account *account;
account->readTopLevelFolders( |
myFolderCallback &folderCallback, |
myCallback &callback); |
A mail account contains folders that are arranged in a
tree-like hierarchy. mail::account::readTopLevelFolders
enumerates the folders at the top level of the mail account's
hierarchy. The rest of the folders may be enumerated by
recursively invoking the mail::folder::readSubFolders(3x)
method.
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.
The folderCallback.success
method receives a vector of pointers to mail::folder objects, that enumerates the
folders at the top level of the mail account's folder
hierarchy.
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).
callback's
success method is then invoked,
after all mail::folder
objects are destroyed.
The list of top-level folders depends on the mail
account's type. Local mail accounts have a single folder
object representing the locally-configured mail folder
directory. inbox and
maildir accounts also have a
single folder named INBOX.
INBOX represents the system mail
folder where incoming mail is delivered. pop3 accounts have a single, lonely,
INBOX folder. imap accounts have a INBOX folder in addition to top level
folders identified by the IMAP server (using the IMAP
NAMESPACE extension). IMAP
servers that do not explicitly identify folder collections
will have a single mail::folder object, representing the
root of the IMAP server's namespace.