<<< Previous |  | Next >>>

# mail::folder::createSubFolder

## Name

mail::folder::createSubFolder -- Create a new folder

## Synopsis

#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`);`

## USAGE

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.

NOTE: | 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.

NOTE:

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.

NOTE:

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.

NOTE:

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.

## RETURN CODES AND CALLBACKS

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.

NOTE: | 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.

NOTE:

`mail::folder`s are linked to their corresponding `mail::account`s. A `mail::folder` created by one `mail::account` may not be used with a different `mail::folder`. All `mail::folder`s 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::folder`s, after their a `mail::account` is destroyed.

NOTE: | 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.

NOTE: | 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).

NOTE:

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.

## SEE ALSO

mail::folder::clone(3x), mail::folder::create(3x), mail::folder::destroy(3x), mail::folder::readSubFolders(3x), mail::folder::renameFolder(3x).

<<< Previous | Home | Next >>>
mail::folder::create | Up | mail::folder::delRights