mail::folder::readSubFolders.3x

Langue: en

Autres versions - même langue

Version: 11/28/2008 (fedora - 01/12/10)

Section: 3 (Bibliothèques de fonctions)

NAME

mail::folder::readSubFolders - Enumerate subfolders

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->readSubFolders(myFolderCallback &folderCallback, myCallback &callback);

USAGE

A mail account contains folders that are arranged in a tree-like hierarchy. mail::folder::readSubFolders enumerates folder's subfolders.


Note

Use mail::folder::hasSubFolders(3x) to check if folder contains subfolders, and invoke mail::folder::readSubFolders only if mail::folder::hasSubFolders returns true.

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.

The folderCallback.success method receives a vector of pointers to mail::folder objects, that enumerates folder's subfolders. The vector will be empty if folder does not have any subfolders.


Note

Subfolders received by mail::callback::folder::success are linked to the same account that folder is linked to.


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).

callback's success method is then invoked, after all mail::folder objects are destroyed.

SEE ALSO

mail::account::readTopLevelFolders(3x), mail::folder::clone(3x), mail::folder::getParentFolder(3x).