mail::account::readTopLevelFolders(3x)

1mail::account::readTopLmeaviell:F:oalcdceorusn(t3xN)ativmeaiAlP:I:arcecfoeurnetn:c:ereadTopLevelFolders(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
26
27       account->readTopLevelFolders (myFolderCallback &folderCallback, myCall‐
28       back &callback);
29

USAGE

31       A mail account contains folders that are arranged in a tree-like  hier‐
32       archy.   mail::account::readTopLevelFolders  enumerates  the folders at
33       the top level of the mail account's hierarchy.  The rest of the folders
34       may  be  enumerated  by recursively invoking the mail::folder::readSub‐
35       Folders(3x) method.
36

RETURN CODES AND CALLBACKS

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

NAME

SYNOPSIS

USAGE

RETURN CODES AND CALLBACKS

SEE ALSO