1MAIL::FOLDER::OPEN(3x) Cone: COnsole Newsreader And E MAIL::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,
44 myFolderCallback &folderCallback);
45
47 A mail folder must be formally "opened" before the messages in the
48 folder may be accessed. Each mail account can have only one mail folder
49 at any time Opening another folder automatically "closes" the previous
50 folder.
51 Note
53 Different mail::account or mail::ACCOUNT objects may each have a
54 folder opened, at the same time. It is possible to create multiple
55 mail::account or mail::ACCOUNT objects that refer to the same
56 actual mail account. Whether it is possible to access the same
57 account multiple times, using different objects, and whether each
58 object may have the same folder opened depends on the account type
59 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 access
74 to local maildirs generally works well, however simultaneous
75 access to the same mbox folder may be rather slow, due to the
76 overhead of locking and rescanning of the folder by each
77 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
86 folderCallback until either the mail::account is destroyed, or another
87 folder is opened. Changes to the folder´s contents are reflected by
88 invoking folderCallback´s methods.
89 folderCallback´s methods are usually invoked by
91 mail::account::removeMessages(3x),
92 mail::account::updateFolderIndexInfo(3x),
93 mail::account::saveFolderIndexInfo(3x),
94 mail::account::updateFolderIndexFlags(3x), and
95 mail::account::checkNewMail(3x), however the application must be
96 prepared to handle any folderCallback´s method to be invoked at any
97 time. Most mail servers reserve the right to notify the client of
98 changes to the folder´s contents at any time.
99 Note
101 As always, messages are numbered starting with 0. That is, a folder
102 with ten messages contains messages #0 through #9.
103 void newMessages()
105 This method is invoked whenever new messages are added to the
106 currently open folder. The application should use
107 mail::account::getFolderIndexSize(3x) to determine how many
108 messages now exist in the current folder, and use the number of
109 messages the application already knows about to determine how many
110 new messages have been added.
111 Example: The application already knows that the folder has three
113 messages. After mail::callback::folder::newMessages is invoked
114 mail::account::getFolderIndexSize(3x) now claims there are five
115 messages in the folder. This means that the last two messages in
116 the folder are new messages.
117 void messagesRemoved(vector< pair<size_t, size_t> > &removedList);
119 Messages were removed from the folder, and the remaining messages
120 have been renumbered to fill in the gaps. removedList is an array
121 that lists which messages were removed. Each array element contains
122 a starting range and an ending range. The range “7-9” specifies
123 that messages #7 through #9, three messages overall, were removed.
124 The range “5-5” specifies that message #5 was removed.
125 The remaining messages have been renumbered. For example, if the
127 application knows that the folder has ten messages, then if
128 removedList contains two ranges: “3-3”, and “5-7”, this indicates
129 that messages #3, #5, #6, and #7 were removed. The old message #4
130 is now message #3, the old mesasge #8 is now message #4, and the
131 old message #9 is now message #5, and there are now six messages
132 left in the folder.
133 void messageChanged(size_t messageNumber)
135 The flags of the indicated message have changed. The application
136 should use mail::account::getFolderIndexInfo(3x) to read the
137 current message flags.
138 Snapshots
140 Folder index snapshots are implemented by some mail account types.
141 Folder index snapshots allow large folders to be opened quickly. If a
142 folder contains many messages,
143 LibMAIL may take a long time to open a folder. Folder index snapshots
147 speed up the process of opening a folder which was recently opened. At
148 this time, folder index snapshots are implemented with NNTP, pop3, and
149 SMAP-based accounts. Attempts to use folder index snapshots with other
150 account types will be quietly ignored.
151 Implementing folder index snapshots is optional. restoreSnapshot may
153 be NULL, and Cone will open folder the old-fashional way, by patiently
154 downloading the entire folder index when opening the folder. To
155 implement snapshots the application must implemented the saveSnapshot
156 method of its mail::callback::folder subclass, then pass a pointer to a
157 mail::snapshot subclass to mail::folder::open
158 Applications can pass a NULL pointer, and not define saveSnapshot if
160 folder index snapshots are not needed. If mail::folder::open receives a
161 non-NULL pointer, the object must not be destroyed until callback´s
162 success or fail method is invoked.
163 When snapshots are enabled,
165 LibMAIL invokes mail::callback::folder::saveSnapshot whenever a
169 snapshot of the opened folder´s index should be saved.
170 mail::callback::folder::saveSnapshot gets invoked periodically as long
171 as the folder remains open. mail::callback::folder::saveSnapshot
172 receives an opaque identifier, snapshotId.
173 mail::callback::folder::saveSnapshot should use
174 mail::account::getFolderIndexSize(3x) to obtain the number of messages
175 in the folder, then use mail::account::getFolderIndexInfo(3x) to save
176 each message´s folder index entry, alongside with the snapshotId, and
177 the total number of messages.
178 mail::messageInfo has a convenient operator string() that converts the
180 entire object into a string, and a corresponding constructor that
181 initializes the entire mail::messageInfo object from a string.
182 The application needs only to save the most recent snapshot.
184 mail::callback::folder::saveSnapshot should discard any
185 previously-saved snapshot, and replace it with the current one.
186 mail::callback::folder::saveSnapshot should not invoke any other
187 LibMAIL methods, except mail::account::getFolderIndexSize(3x) and
191 mail::account::getFolderIndexInfo(3x).
192 The mail::snapshot-subclassed object passed to mail::folder::open
194 implements two methods: getSnapShotInfo and restoreSnapshot.
195 getSnapShotInfo should initialize snapshotId to the opaque snapshot
196 identifier of the most-recently saved snapshot, and nMessages to the
197 number of messages in the snapshot.
198 An application that does not have a snapshot, but wishes to use
200 snapshots (perhaps this is the very first time this folder was opened)
201 should initialize snapshotId to an empty string, and set nMessages to
202 zero. The application should not pass a NULL restoreSnapshot parameter,
203 since that disables
204 LibMAIL ´s usage of snapshots.
208 After invoking getSnapShotInfo,
210 LibMAIL will invoke restoreSnapshot, at which time the application
214 needs to restore the folder index as it was saved by the snapshot.
215 restoreSnapshot receives a reference to a mail::snapshot::restore
216 object, which contains two methods:
217 void restoreIndex(size_t msgNum, const mail::messageInfo &msgInfo);
219 Repeatedly invoke this function to specify the previously saved
220 mail::messageInfo of each message.
221 void abortRestore()
223 After restoring the entire folder index, restoreSnapshot should
224 simply terminate. If the application cannot restore the entire
225 folder index, for some reason, abortRestore should be invoke to
226 invalidate any partially-restored index data.
227 Note
229 With POP3 accounts, message status flags are going to be preserved
230 only when snapshots are used. The POP3 does not provide any
231 facility for saving message status flags; and without snapshots
232 each time a POP3 folder is opened all messages will be seen as new
233 messages. Using snapshots saves each message´s status, and restores
234 it when the POP3 folder is reopened.
235
237 The application must wait until callback´s success or fail method is
238 invoked. The success method is invoked when this request is succesfully
239 processed. The fail method is invoked if this request cannot be
240 processed. The application must not destroy callback until either the
241 success or fail method is invoked.
242 Note
244 callback´s fail method may be invoked even after other callback
245 methods were invoked. This indicates that the request was partially
246 completed before the error was encountered.
247
249 mail::folder::readFolderInfo(3x), mail::account::checkNewMail(3x),
250 mail::account::getFolderIndexInfo(3x),
251 mail::account::getFolderIndexSize(3x),
252 mail::account::removeMessages(3x),
253 mail::account::saveFolderIndexInfo(3x),
254 mail::account::updateFolderIndexFlags(3x),
255 mail::account::updateFolderIndexInfo(3x).
256[FIXME: source] 05/08/2010 MAIL::FOLDER::OPEN(3x)