mail::folder::open — Open a folder
        
        
        #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);
        };
        
| folder->open( | myCallback &callback, | 
| myRestoreSnapshot &restoreSnapshot, | |
| myFolderCallback
            &folderCallback ); | 
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.
Different mail::account or mail::ACCOUNT objects may each have a folder opened, at the same time. It is possible to create multiple mail::account or mail::ACCOUNT objects that refer to the same actual mail account. Whether it is possible to access the same account multiple times, using different objects, and whether each object may have the same folder opened depends on the account type and/or the remote server.
Whether it's possible to open the same remote IMAP or POP3 account more than once depends on the remote IMAP/POP3 server.
Whether it's possible to open the same folder on a remote IMAP server account more than once depends on the remote IMAP/POP3 server. Most IMAP servers allow the same account to be opened more than once, as long as the different login sessions do not try to open the same folder. Some IMAP servers allow the same folder to be opened simultaneously by multiple sessions.
It is generally possible to open the same local mail folder simultaneously, via multiple mail::account objects, as long as only one pending request is issued at a time. Concurrent access to local maildirs generally works well, however simultaneous access to the same mbox folder may be rather slow, due to the overhead of locking and rescanning of the folder by each mail::account object.
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.
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.
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.
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).