mail::account::readTopLevelFolders
Prev | mail::account Native API reference | Next

## Name

mail::account::readTopLevelFolders — Enumerate top-level folders

## 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::account *account;

`account->fsfuncreadTopLevelFolders(` | myFolderCallback &folderCallback,
| myCallback &callback`)`;

## USAGE

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.

## 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 the folders at the top level of the mail account's folder hierarchy.

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

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.

## SEE ALSO

mail::folder::readSubFolders(3x), mail::folder::clone(3x)..

Prev | Up | Next
mail::account::readMessageContentDecoded | Home | ToC | mail::account::removeMessages