mail::account::readTopLevelFolders(3x)

1MAIL::ACCOUNT::READT(3x)Cone: COnsole Newsreader And EMAIL::ACCOUNT::READT(3x)
2
3
4

NAME

6       mail::account::readTopLevelFolders - Enumerate top-level folders
7

SYNOPSIS

9       #include <libmail/mail.H>
10
11
12       class myCallback : public mail::callback {
13       public:
14           void success(std::string msg);
15           void fail(std::string msg);
16       };
17
18       class myFolderCallback : public mail::callback::folderlist {
19       public:
20           void success(const std::vector<const mail::folder *> &folders);
21       };
22
23       mail::account *account;
24
25       account->readTopLevelFolders(myFolderCallback &folderCallback,
26                                    myCallback &callback);
27

USAGE

29       A mail account contains folders that are arranged in a tree-like
30       hierarchy.  mail::account::readTopLevelFolders enumerates the folders
31       at the top level of the mail account´s hierarchy. The rest of the
32       folders may be enumerated by recursively invoking the
33       mail::folder::readSubFolders(3x) method.
34

RETURN CODES AND CALLBACKS

36       The application must wait until callback´s success or fail method is
37       invoked. The success method is invoked when this request is succesfully
38       processed. The fail method is invoked if this request cannot be
39       processed. The application must not destroy callback until either the
40       success or fail method is invoked.
41
42           Note
43           callback´s fail method may be invoked even after other callback
44           methods were invoked. This indicates that the request was partially
45           completed before the error was encountered.
46
47           Note
48           The application must not destroy folderCallback until this request
49           fails or succeeds.  folderCallback´s success method is invoked just
50           before the callback´s success method.
51
52       The folderCallback.success method receives a vector of pointers to
53       mail::folder objects, that enumerates the folders at the top level of
54       the mail account´s folder hierarchy.
55
56           Note
57           mail::folders are linked to their corresponding mail::accounts. A
58           mail::folder created by one mail::account may not be used with a
59           different mail::folder. All mail::folders created by a
60           mail::account are invalidated when this mail::account object is
61           destroyed. Note that the mail::folder objects are not automatically
62           destroyed; the application is still responsible for destroying any
63           remaining mail::folders, after their a mail::account is destroyed.
64
65           Note
66           The folderCallback.success method receives a (possibly empty)
67           vector of pointers to mail::folder objects. These objects will be
68           destroyed when folderCallback.success terminates. The application
69           must use mail::folder::clone(3x) to create copies of mail::folder
70           objects it wants to use later.
71
72           Note
73           Both folderCallback.success and myCallback.success method will be
74           invoked if this request succeeds.  folderCallback.success will be
75           invoked before myCallback.success (since by definition this
76           indicates that the request has been completed).
77
78       callback´s success method is then invoked, after all mail::folder
79       objects are destroyed.
80
81       The list of top-level folders depends on the mail account´s type. Local
82       mail accounts have a single folder object representing the
83       locally-configured mail folder directory.  inbox and maildir accounts
84       also have a single folder named INBOX.  INBOX represents the system
85       mail folder where incoming mail is delivered.  pop3 accounts have a
86       single, lonely, INBOX folder.  imap accounts have a INBOX folder in
87       addition to top level folders identified by the IMAP server (using the
88       IMAP NAMESPACE extension). IMAP servers that do not explicitly identify
89       folder collections will have a single mail::folder object, representing
90       the root of the IMAP server´s namespace.
91

NAME

SYNOPSIS

USAGE

RETURN CODES AND CALLBACKS

SEE ALSO