mail::folder::createSubFolder — Create a new folder
        
        
        #include <libmail/mail.H>
        
        
        class myCallback : public mail::callback {
        public:
            void success(std::string msg);
            void fail(std::string msg);
        };
        class myFolderCallback : public mail::callback::folderlist {
        public:
            void success(const std::vector<const mail::folder *> &folders);
        };
        mail::folder *folder;
| folder->createSubFolder( | std::string name, | 
| bool createDirectory, | |
| myFolderCallback &folderCallback, | |
| myCallback &callback ); | 
Most mail accounts support the ability to create and
      delete folders, which are arranged in a tree-like hierarchy.
      mail::folder::createSubFolder
      creates a new folder, as a subfolder of folder (which does not
      necessarily have to refer the currently open folder; it may
      be any mail::folder object
      that's associated with an active mail::account).
Folders may be created in IMAP accounts, and local mail (either mbox or maildir) accounts. Folders cannot be created in POP3 accounts, as this functionality is not supported by the POP3 protocol (this operation will fail).
There are two types of folders: folder that contain
      messages (regular folders), and folders that contain other
      sub-folders ("folder directories", or "directories" for
      short). isDirectory
      specifies whether the new folder is a regular folder, or a
      folder directory.
Local maildir-based accounts, and some IMAP servers, are
        capable of supporting so-called "dual-purpose" folders;
        folders that contain both messages and other sub-folders. A
        dual-purpose folder may be created by invoking mail::folder::createSubFolder twice, once
        with isDirectory
        set to false; and a second
        time with isDirectory set to
        true, specifying the same
        name both
        times.
name specifies the
      name of the new folder, in the application's character
      set.
Some mail servers reserve certain characters which
        cannot be used in folder names. IMAP mail servers use a
        special character (usually "/"
        or ".") as a separator between
        names in a hierarchical folder path. The actual character
        varies from server to server. An attempt to create/rename a
        folder whose name includes a reserved character will fail.
        Different IMAP servers use different hierarchy separator
        characters. An attempt to create a folder may fail on one
        IMAP server even if another IMAP server can succesfully
        create a folder with the same name. This is, unfortunately,
        a design flaw in the IMAP protocol.
Maildir folders created by are compatible and can be
        read by the Courier-IMAP server. Names of maildir folders
        may contain any character, including the characters
        ":", "/", ".",
        "~", and ":". However, if the same folders are
        exported via IMAP, folders whose name includes these
        characters may not be readable by some IMAP clients. Even a
        LibMAIL application may
        not be able to read one of these folders via IMAP.
Mbox mail folders created by LibMAIL are mostly compatible and can
        be exported by IMAP servers that read mbox-formatted mail
        folders (with some limitations, such as that the same mbox
        folder cannot be open by LibMAIL and another application at the
        same time). Names of mbox folders can contain any
        character, including the characters "/", and "~".
        However if mbox folders are exported via IMAP, folders
        whose name includes these characters may not be readable by
        some IMAP clients.
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.
The application must not destroy folderCallback until this
        request fails or succeeds. folderCallback's success method is invoked just before the
        callback's
        success method.
If the folder was succesfully created, the folderCallback.success method receives a
      vector that contains a single pointer to a mail::folder object. The mail::folder object will refer to the
      newly-created folder.
mail::folders are linked to their corresponding mail::accounts. A mail::folder created by one mail::account may not be used with a different mail::folder. All mail::folders created by a mail::account are invalidated when this mail::account object is destroyed. Note that the mail::folder objects are not automatically destroyed; the application is still responsible for destroying any remaining mail::folders, after their a mail::account is destroyed.
The folderCallback.success
        method receives a (possibly empty) vector of pointers to
        mail::folder objects. These
        objects will be destroyed when folderCallback.success terminates. The
        application must use mail::folder::clone(3x)
        to create copies of mail::folder objects it wants to use
        later.
Both folderCallback.success and myCallback.success method will be invoked
        if this request succeeds. folderCallback.success will be invoked
        before myCallback.success
        (since by definition this indicates that the request has
        been completed).
For some kinds of accounts, mail::folder::readSubFolders(3x) may not enumerate new folder directories until they contain at least one folder. Therefore the recommended process to create a new folder directory is as follows:
Invoke mail::folder::createSubFolder to
              request the creation of a new folder directory.
In folderCallback.success, use
              mail::folder::clone(3x)
              to save a copy of the mail::folder object which refers
              to the new folder directory.
After the myCallback.success method is
              invoked, use the saved mail::folder object's
              createSubFolder method
              to create a new folder in the new folder
              directory.