#include <libmail/mail.H>
class myCallback : public mail::callback {
public:
void success(std::string msg);
void fail(std::string msg);
};
#include <libmail/snapshot.H>
class myFolderCallback : public mail::callback::folder {
public:
void newMessages();
void messagesRemoved(vector< pair<size_t, size_t> > &removedList);
void messageChanged(size_t messageNumber);
void saveSnapshot(std::string snapshotId);
};
class myRestoreSnapshot : public mail::snapshot {
public:
void getSnapshotInfo(std::string &snapshotId,
size_t &nMessages);
void restoreSnapshot(mail::snapshot::restore &restoreCB);
};
A mail folder must be formally "opened" before the messages in the folder may be accessed. Each mail account can have only one mail folder at any time Opening another folder automatically "closes" the previous folder.
NOTE: | Different
|
Any previously-opened folder is closed before the an attempt to open this folder is made. If the new folder cannot be opened, the previous folder is still considered closed.
The folderCallback object is used to notify the
application of changes to the folder's contents.
The application must not destroy
folderCallback until either the
mail::account
is destroyed, or another folder
is opened.
Changes to the folder's contents are reflected by invoking
folderCallback's methods.
folderCallback's methods are usually invoked by mail::account::removeMessages(3x), mail::account::updateFolderIndexInfo(3x), mail::account::saveFolderIndexInfo(3x), mail::account::updateFolderIndexFlags(3x), and mail::account::checkNewMail(3x), however the application must be prepared to handle any folderCallback's method to be invoked at any time. Most mail servers reserve the right to notify the client of changes to the folder's contents at any time.
NOTE: | As always, messages are numbered starting with 0. That is, a folder with ten messages contains messages #0 through #9. |
This method is invoked whenever new messages are added to the currently open folder. The application should use mail::account::getFolderIndexSize(3x) to determine how many messages now exist in the current folder, and use the number of messages the application already knows about to determine how many new messages have been added.
Example: The application already knows that the folder has three messages. After mail::callback::folder::newMessages is invoked mail::account::getFolderIndexSize(3x) now claims there are five messages in the folder. This means that the last two messages in the folder are new messages.
Messages were removed from the folder, and the remaining messages have been renumbered to fill in the gaps. removedList is an array that lists which messages were removed. Each array element contains a starting range and an ending range. The range "7-9" specifies that messages #7 through #9, three messages overall, were removed. The range "5-5" specifies that message #5 was removed.
The remaining messages have been renumbered. For example, if the application knows that the folder has ten messages, then if removedList contains two ranges: "3-3", and "5-7", this indicates that messages #3, #5, #6, and #7 were removed. The old message #4 is now message #3, the old mesasge #8 is now message #4, and the old message #9 is now message #5, and there are now six messages left in the folder.
The flags of the indicated message have changed. The application should use mail::account::getFolderIndexInfo(3x) to read the current message flags.
Folder index snapshots are implemented by some mail account types. Folder index snapshots allow large folders to be opened quickly. If a folder contains many messages, LibMAIL may take a long time to open a folder. Folder index snapshots speed up the process of opening a folder which was recently opened. At this time, folder index snapshots are implemented with NNTP, pop3, and SMAP-based accounts. Attempts to use folder index snapshots with other account types will be quietly ignored.
Implementing folder index snapshots is optional.
restoreSnapshot may be NULL,
and Cone will open folder the old-fashional way, by
patiently downloading the entire folder index when opening the folder.
To implement snapshots the application must implemented the
saveSnapshot method of its
mail::callback::folder
subclass, then
pass a pointer to a mail::snapshot
subclass to
mail::folder::open
Applications can pass a NULL pointer, and not define saveSnapshot if folder index snapshots are not needed. If mail::folder::open receives a non-NULL pointer, the object must not be destroyed until callback's success or fail method is invoked.
When snapshots are enabled, LibMAIL invokes mail::callback::folder::saveSnapshot whenever a snapshot of the opened folder's index should be saved. mail::callback::folder::saveSnapshot gets invoked periodically as long as the folder remains open. mail::callback::folder::saveSnapshot receives an opaque identifier, snapshotId. mail::callback::folder::saveSnapshot should use mail::account::getFolderIndexSize(3x) to obtain the number of messages in the folder, then use mail::account::getFolderIndexInfo(3x) to save each message's folder index entry, alongside with the snapshotId, and the total number of messages.
mail::messageInfo
has a convenient
operator string() that converts the entire object
into a string, and a corresponding constructor that initializes the entire
mail::messageInfo
object from a string.
The application needs only to save the most recent snapshot. mail::callback::folder::saveSnapshot should discard any previously-saved snapshot, and replace it with the current one. mail::callback::folder::saveSnapshot should not invoke any other LibMAIL methods, except mail::account::getFolderIndexSize(3x) and mail::account::getFolderIndexInfo(3x).
The mail::snapshot
-subclassed object passed to
mail::folder::open implements two methods:
getSnapShotInfo and
restoreSnapshot.
getSnapShotInfo should initialize
snapshotId to the opaque snapshot identifier of the
most-recently saved snapshot, and
nMessages to the number of messages in the
snapshot.
An application that does not have a snapshot, but wishes to use snapshots (perhaps this is the very first time this folder was opened) should initialize snapshotId to an empty string, and set nMessages to zero. The application should not pass a NULL restoreSnapshot parameter, since that disables LibMAIL 's usage of snapshots.
After invoking
getSnapShotInfo,
LibMAIL
will invoke
restoreSnapshot,
at which time the application needs to restore the folder index as it was
saved by the snapshot.
restoreSnapshot
receives a reference to a
mail::snapshot::restore
object, which contains
two methods:
Repeatedly invoke this function to specify the previously saved
mail::messageInfo
of each message.
After restoring the entire folder index, restoreSnapshot should simply terminate. If the application cannot restore the entire folder index, for some reason, abortRestore should be invoke to invalidate any partially-restored index data.
NOTE: | With POP3 accounts, message status flags are going to be preserved only when snapshots are used. The POP3 does not provide any facility for saving message status flags; and without snapshots each time a POP3 folder is opened all messages will be seen as new messages. Using snapshots saves each message's status, and restores it when the POP3 folder is reopened. |
The application must wait until callback's success or fail method is invoked. The success method is invoked when this request is succesfully processed. The fail method is invoked if this request cannot be processed. The application must not destroy callback until either the success or fail method is invoked.
NOTE: | callback's fail method may be invoked even after other callback methods were invoked. This indicates that the request was partially completed before the error was encountered. |
mail::folder::readFolderInfo(3x), mail::account::checkNewMail(3x), mail::account::getFolderIndexInfo(3x), mail::account::getFolderIndexSize(3x), mail::account::removeMessages(3x), mail::account::saveFolderIndexInfo(3x), mail::account::updateFolderIndexFlags(3x), mail::account::updateFolderIndexInfo(3x).
<<< Previous | Home | Next >>> |
mail::folder::isparentof | Up | mail::folder::readFolderInfo |