1 Cone©
2MAIL::FOLDER::OPEN(3x) Cone: COnsole Newsreader And E MAIL::FOLDER::OPEN(3x)
4
8 mail::folder::open - Open a folder
9
11 #include <libmail/mail.H>
12 class myCallback : public mail::callback {
15 public:
16 void success(std::string msg);
17 void fail(std::string msg);
18 };
19 #include <libmail/snapshot.H>
21 class myFolderCallback : public mail::callback::folder {
23 public:
25 void newMessages();
26 void messagesRemoved(vector< pair<size_t, size_t> > &removedList);
28 void messageChanged(size_t messageNumber);
30 void saveSnapshot(std::string snapshotId);
32 };
34 class myRestoreSnapshot : public mail::snapshot {
36 public:
38 void getSnapshotInfo(std::string &snapshotId,
39 size_t &nMessages);
40 void restoreSnapshot(mail::snapshot::restore &restoreCB);
42 };
43 folder->open(myCallback &callback, myRestoreSnapshot &restoreSnapshot,
46 myFolderCallback &folderCallback);
47
49 A mail folder must be formally "opened" before the messages in the
50 folder may be accessed. Each mail account can have only one mail folder
51 at any time Opening another folder automatically "closes" the previous
52 folder.
53 Note
55 Different mail::account or mail::ACCOUNT objects may each have a
56 folder opened, at the same time. It is possible to create multiple
57 mail::account or mail::ACCOUNT objects that refer to the same
58 actual mail account. Whether it is possible to access the same
59 account multiple times, using different objects, and whether each
60 object may have the same folder opened depends on the account type
61 and/or the remote server.
62 · Whether it's possible to open the same remote IMAP or POP3
64 account more than once depends on the remote IMAP/POP3 server.
65 · Whether it's possible to open the same folder on a remote IMAP
67 server account more than once depends on the remote IMAP/POP3
68 server. Most IMAP servers allow the same account to be opened
69 more than once, as long as the different login sessions do not
70 try to open the same folder. Some IMAP servers allow the same
71 folder to be opened simultaneously by multiple sessions.
72 · It is generally possible to open the same local mail folder
74 simultaneously, via multiple mail::account objects, as long as
75 only one pending request is issued at a time. Concurrent access
76 to local maildirs generally works well, however simultaneous
77 access to the same mbox folder may be rather slow, due to the
78 overhead of locking and rescanning of the folder by each
79 mail::account object.
80 Any previously-opened folder is closed before the an attempt to open
82 this folder is made. If the new folder cannot be opened, the previous
83 folder is still considered closed.
84 Folder Updates
86 The folderCallback object is used to notify the application of changes
87 to the folder's contents. The application must not destroy
88 folderCallback until either the mail::account is destroyed, or another
89 folder is opened. Changes to the folder's contents are reflected by
90 invoking folderCallback's methods.
91 folderCallback's methods are usually invoked by
93 mail::account::removeMessages(3x),
94 mail::account::updateFolderIndexInfo(3x),
95 mail::account::saveFolderIndexInfo(3x),
96 mail::account::updateFolderIndexFlags(3x), and
97 mail::account::checkNewMail(3x), however the application must be
98 prepared to handle any folderCallback's method to be invoked at any
99 time. Most mail servers reserve the right to notify the client of
100 changes to the folder's contents at any time.
101 Note
103 As always, messages are numbered starting with 0. That is, a folder
104 with ten messages contains messages #0 through #9.
105 void newMessages()
107 This method is invoked whenever new messages are added to the
108 currently open folder. The application should use
109 mail::account::getFolderIndexSize(3x) to determine how many
110 messages now exist in the current folder, and use the number of
111 messages the application already knows about to determine how many
112 new messages have been added.
113 Example: The application already knows that the folder has three
115 messages. After mail::callback::folder::newMessages is invoked
116 mail::account::getFolderIndexSize(3x) now claims there are five
117 messages in the folder. This means that the last two messages in
118 the folder are new messages.
119 void messagesRemoved(vector< pair<size_t, size_t> > &removedList);
121 Messages were removed from the folder, and the remaining messages
122 have been renumbered to fill in the gaps. removedList is an array
123 that lists which messages were removed. Each array element contains
124 a starting range and an ending range. The range “7-9” specifies
125 that messages #7 through #9, three messages overall, were removed.
126 The range “5-5” specifies that message #5 was removed.
127 The remaining messages have been renumbered. For example, if the
129 application knows that the folder has ten messages, then if
130 removedList contains two ranges: “3-3”, and “5-7”, this indicates
131 that messages #3, #5, #6, and #7 were removed. The old message #4
132 is now message #3, the old mesasge #8 is now message #4, and the
133 old message #9 is now message #5, and there are now six messages
134 left in the folder.
135 void messageChanged(size_t messageNumber)
137 The flags of the indicated message have changed. The application
138 should use mail::account::getFolderIndexInfo(3x) to read the
139 current message flags.
140 Snapshots
142 Folder index snapshots are implemented by some mail account types.
143 Folder index snapshots allow large folders to be opened quickly. If a
144 folder contains many messages, LibMAIL may take a long time to open a
145 folder. Folder index snapshots speed up the process of opening a folder
146 which was recently opened. At this time, folder index snapshots are
147 implemented with NNTP, pop3, and SMAP-based accounts. Attempts to use
148 folder index snapshots with other account types will be quietly
149 ignored.
150 Implementing folder index snapshots is optional. restoreSnapshot may
152 be NULL, and Cone will open folder the old-fashional way, by patiently
153 downloading the entire folder index when opening the folder. To
154 implement snapshots the application must implemented the saveSnapshot
155 method of its mail::callback::folder subclass, then pass a pointer to a
156 mail::snapshot subclass to mail::folder::open
157 Applications can pass a NULL pointer, and not define saveSnapshot if
159 folder index snapshots are not needed. If mail::folder::open receives a
160 non-NULL pointer, the object must not be destroyed until callback's
161 success or fail method is invoked.
162 When snapshots are enabled, LibMAIL invokes
164 mail::callback::folder::saveSnapshot whenever a snapshot of the opened
165 folder's index should be saved. mail::callback::folder::saveSnapshot
166 gets invoked periodically as long as the folder remains open.
167 mail::callback::folder::saveSnapshot receives an opaque identifier,
168 snapshotId. mail::callback::folder::saveSnapshot should use
169 mail::account::getFolderIndexSize(3x) to obtain the number of messages
170 in the folder, then use mail::account::getFolderIndexInfo(3x) to save
171 each message's folder index entry, alongside with the snapshotId, and
172 the total number of messages.
173 mail::messageInfo has a convenient operator string() that converts the
175 entire object into a string, and a corresponding constructor that
176 initializes the entire mail::messageInfo object from a string.
177 The application needs only to save the most recent snapshot.
179 mail::callback::folder::saveSnapshot should discard any
180 previously-saved snapshot, and replace it with the current one.
181 mail::callback::folder::saveSnapshot should not invoke any other
182 LibMAIL methods, except mail::account::getFolderIndexSize(3x) and
183 mail::account::getFolderIndexInfo(3x).
184 The mail::snapshot-subclassed object passed to mail::folder::open
186 implements two methods: getSnapShotInfo and restoreSnapshot.
187 getSnapShotInfo should initialize snapshotId to the opaque snapshot
188 identifier of the most-recently saved snapshot, and nMessages to the
189 number of messages in the snapshot.
190 An application that does not have a snapshot, but wishes to use
192 snapshots (perhaps this is the very first time this folder was opened)
193 should initialize snapshotId to an empty string, and set nMessages to
194 zero. The application should not pass a NULLrestoreSnapshot parameter,
195 since that disables LibMAIL 's usage of snapshots.
196 After invoking getSnapShotInfo, LibMAIL will invoke restoreSnapshot, at
198 which time the application needs to restore the folder index as it was
199 saved by the snapshot. restoreSnapshot receives a reference to a
200 mail::snapshot::restore object, which contains two methods:
201 void restoreIndex(size_t msgNum, const mail::messageInfo &msgInfo);
203 Repeatedly invoke this function to specify the previously saved
204 mail::messageInfo of each message.
205 void abortRestore()
207 After restoring the entire folder index, restoreSnapshot should
208 simply terminate. If the application cannot restore the entire
209 folder index, for some reason, abortRestore should be invoke to
210 invalidate any partially-restored index data.
211 Note
213 With POP3 accounts, message status flags are going to be preserved
214 only when snapshots are used. The POP3 does not provide any
215 facility for saving message status flags; and without snapshots
216 each time a POP3 folder is opened all messages will be seen as new
217 messages. Using snapshots saves each message's status, and restores
218 it when the POP3 folder is reopened.
219
221 The application must wait until callback's success or fail method is
222 invoked. The success method is invoked when this request is succesfully
223 processed. The fail method is invoked if this request cannot be
224 processed. The application must not destroy callback until either the
225 success or fail method is invoked.
226 Note
228 callback's fail method may be invoked even after other callback
229 methods were invoked. This indicates that the request was partially
230 completed before the error was encountered.
231
233 mail::folder::readFolderInfo(3x), mail::account::checkNewMail(3x),
234 mail::account::getFolderIndexInfo(3x),
235 mail::account::getFolderIndexSize(3x),
236 mail::account::removeMessages(3x),
237 mail::account::saveFolderIndexInfo(3x),
238 mail::account::updateFolderIndexFlags(3x),
239 mail::account::updateFolderIndexInfo(3x).
240
242 Sam Varshavchik
243Cone© 08/25/2016 MAIL::FOLDER::OPEN(3x)