1MAIL::FOLDER::OPEN(3x) mail::folder Native API referenceMAIL::FOLDER::OPEN(3x)
2
6 mail::folder::open - Open a folder
7
9 #include <libmail/mail.H>
10 class myCallback : public mail::callback {
13 public:
14 void success(std::string msg);
15 void fail(std::string msg);
16 };
17 #include <libmail/snapshot.H>
19 class myFolderCallback : public mail::callback::folder {
21 public:
23 void newMessages();
24 void messagesRemoved(vector< pair<size_t, size_t> > &removedList);
26 void messageChanged(size_t messageNumber);
28 void saveSnapshot(std::string snapshotId);
30 };
32 class myRestoreSnapshot : public mail::snapshot {
34 public:
36 void getSnapshotInfo(std::string &snapshotId,
37 size_t &nMessages);
38 void restoreSnapshot(mail::snapshot::restore &restoreCB);
40 };
41 folder->open (myCallback &callback, myRestoreSnapshot &restoreSnapshot,
45 myFolderCallback &folderCallback);
46
48 A mail folder must be formally "opened" before the messages in the
49 folder may be accessed. Each mail account can have only one mail
50 folder at any time Opening another folder automatically "closes" the
51 previous folder.
52 Note: Different mail::account or mail::ACCOUNT objects may each
54 have a folder opened, at the same time. It is possible to cre‐
55 ate multiple mail::account or mail::ACCOUNT objects that refer
56 to the same actual mail account. Whether it is possible to
57 access the same account multiple times, using different objects,
58 and whether each object may have the same folder opened depends
59 on the account type and/or the remote server.
60 · Whether it's possible to open the same remote IMAP or POP3
62 account more than once depends on the remote IMAP/POP3 server.
63 · Whether it's possible to open the same folder on a remote IMAP
65 server account more than once depends on the remote IMAP/POP3
66 server. Most IMAP servers allow the same account to be opened
67 more than once, as long as the different login sessions do not
68 try to open the same folder. Some IMAP servers allow the same
69 folder to be opened simultaneously by multiple sessions.
70 · It is generally possible to open the same local mail folder
72 simultaneously, via multiple mail::account objects, as long as
73 only one pending request is issued at a time. Concurrent
74 access to local maildirs generally works well, however simul‐
75 taneous access to the same mbox folder may be rather slow, due
76 to the overhead of locking and rescanning of the folder by
77 each mail::account object.
78 Any previously-opened folder is closed before the an attempt to open
80 this folder is made. If the new folder cannot be opened, the previous
81 folder is still considered closed.
82 FOLDER UPDATES
84 The folderCallback object is used to notify the application of changes
85 to the folder's contents. The application must not destroy folderCall‐
86 back until either the mail::account is destroyed, or another folder is
87 opened. Changes to the folder's contents are reflected by invoking
88 folderCallback's methods.
89 folderCallback's methods are usually invoked by
91 mail::account::removeMessages(3x), mail::account::updateFolderIndex‐
92 Info(3x), mail::account::saveFolderIndexInfo(3x),
93 mail::account::updateFolderIndexFlags(3x), and mail::account::checkNew‐
94 Mail(3x), however the application must be prepared to handle any fold‐
95 erCallback's method to be invoked at any time. Most mail servers
96 reserve the right to notify the client of changes to the folder's con‐
97 tents at any time.
98 Note: As always, messages are numbered starting with 0. That
100 is, a folder with ten messages contains messages #0 through #9.
101 void newMessages()
103 This method is invoked whenever new messages are added to the
104 currently open folder. The application should use
105 mail::account::getFolderIndexSize(3x) to determine how many mes‐
106 sages now exist in the current folder, and use the number of
107 messages the application already knows about to determine how
108 many new messages have been added.
109 Example: The application already knows that the folder has three
111 messages. After mail::callback::folder::newMessages is invoked
112 mail::account::getFolderIndexSize(3x) now claims there are five
113 messages in the folder. This means that the last two messages
114 in the folder are new messages.
115 void messagesRemoved(vector< pair<size_t, size_t> > &removedList);
117 Messages were removed from the folder, and the remaining mes‐
118 sages have been renumbered to fill in the gaps. removedList is
119 an array that lists which messages were removed. Each array
120 element contains a starting range and an ending range. The
121 range ``7-9'' specifies that messages #7 through #9, three mes‐
122 sages overall, were removed. The range ``5-5'' specifies that
123 message #5 was removed.
124 The remaining messages have been renumbered. For example, if
126 the application knows that the folder has ten messages, then if
127 removedList contains two ranges: ``3-3'', and ``5-7'', this
128 indicates that messages #3, #5, #6, and #7 were removed. The
129 old message #4 is now message #3, the old mesasge #8 is now mes‐
130 sage #4, and the old message #9 is now message #5, and there are
131 now six messages left in the folder.
132 void messageChanged(size_t messageNumber)
134 The flags of the indicated message have changed. The applica‐
135 tion should use mail::account::getFolderIndexInfo(3x) to read
136 the current message flags.
137 SNAPSHOTS
139 Folder index snapshots are implemented by some mail account types.
140 Folder index snapshots allow large folders to be opened quickly. If a
141 folder contains many messages, LibMAIL may take a long time to open a
142 folder. Folder index snapshots speed up the process of opening a
143 folder which was recently opened. At this time, folder index snapshots
144 are implemented with NNTP, pop3, and SMAP-based accounts. Attempts to
145 use folder index snapshots with other account types will be quietly
146 ignored.
147 Implementing folder index snapshots is optional. restoreSnapshot may
149 be NULL, and Cone will open folder the old-fashional way, by patiently
150 downloading the entire folder index when opening the folder. To imple‐
151 ment snapshots the application must implemented the saveSnapshot method
152 of its mail::callback::folder subclass, then pass a pointer to a
153 mail::snapshot subclass to mail::folder::open
154 Applications can pass a NULL pointer, and not define saveSnapshot if
156 folder index snapshots are not needed. If mail::folder::open receives
157 a non-NULL pointer, the object must not be destroyed until callback's
158 success or fail method is invoked.
159 When snapshots are enabled, LibMAIL invokes mail::call‐
161 back::folder::saveSnapshot whenever a snapshot of the opened folder's
162 index should be saved. mail::callback::folder::saveSnapshot gets
163 invoked periodically as long as the folder remains open. mail::call‐
164 back::folder::saveSnapshot receives an opaque identifier, snapshotId.
165 mail::callback::folder::saveSnapshot should use mail::account::get‐
166 FolderIndexSize(3x) to obtain the number of messages in the folder,
167 then use mail::account::getFolderIndexInfo(3x) to save each message's
168 folder index entry, alongside with the snapshotId, and the total number
169 of messages.
170 mail::messageInfo has a convenient operator string() that converts the
172 entire object into a string, and a corresponding constructor that ini‐
173 tializes the entire mail::messageInfo object from a string.
174 The application needs only to save the most recent snapshot.
176 mail::callback::folder::saveSnapshot should discard any previously-
177 saved snapshot, and replace it with the current one. mail::call‐
178 back::folder::saveSnapshot should not invoke any other LibMAIL methods,
179 except mail::account::getFolderIndexSize(3x) and mail::account::get‐
180 FolderIndexInfo(3x).
181 The mail::snapshot-subclassed object passed to mail::folder::open
183 implements two methods: getSnapShotInfo and restoreSnapshot. getSnap‐
184 ShotInfo should initialize snapshotId to the opaque snapshot identifier
185 of the most-recently saved snapshot, and nMessages to the number of
186 messages in the snapshot.
187 An application that does not have a snapshot, but wishes to use snap‐
189 shots (perhaps this is the very first time this folder was opened)
190 should initialize snapshotId to an empty string, and set nMessages to
191 zero. The application should not pass a NULL restoreSnapshot parame‐
192 ter, since that disables LibMAIL 's usage of snapshots.
193 After invoking getSnapShotInfo, LibMAIL will invoke restoreSnapshot, at
195 which time the application needs to restore the folder index as it was
196 saved by the snapshot. restoreSnapshot receives a reference to a
197 mail::snapshot::restore object, which contains two methods:
198 void restoreIndex(size_t msgNum, const mail::messageInfo &msgInfo);
200 Repeatedly invoke this function to specify the previously saved
201 mail::messageInfo of each message.
202 void abortRestore()
204 After restoring the entire folder index, restoreSnapshot should
205 simply terminate. If the application cannot restore the entire
206 folder index, for some reason, abortRestore should be invoke to
207 invalidate any partially-restored index data.
208 Note: With POP3 accounts, message status flags are going to be
210 preserved only when snapshots are used. The POP3 does not pro‐
211 vide any facility for saving message status flags; and without
212 snapshots each time a POP3 folder is opened all messages will be
213 seen as new messages. Using snapshots saves each message's sta‐
214 tus, and restores it when the POP3 folder is reopened.
215
217 The application must wait until callback's success or fail method is
218 invoked. The success method is invoked when this request is succes‐
219 fully processed. The fail method is invoked if this request cannot be
220 processed. The application must not destroy callback until either the
221 success or fail method is invoked.
222 Note: callback's fail method may be invoked even after other
224 callback methods were invoked. This indicates that the request
225 was partially completed before the error was encountered.
226
228 mail::folder::readFolderInfo(3x), mail::account::checkNewMail(3x),
229 mail::account::getFolderIndexInfo(3x), mail::account::getFolderIndex‐
230 Size(3x), mail::account::removeMessages(3x), mail::account::save‐
231 FolderIndexInfo(3x), mail::account::updateFolderIndexFlags(3x),
232 mail::account::updateFolderIndexInfo(3x).
233 10 April 2006 MAIL::FOLDER::OPEN(3x)