<<< Previous |  | Next >>>

# mail::ACCOUNT::createFolder

## Name

mail::ACCOUNT::createFolder -- Create a new folder

## Synopsis

#include <libmail/sync.H>
mail::ACCOUNT *mail;
mail::folder *folder;

``mail::folder *f=mail->`createFolder``(const mail::folder *`parentFolder`, std::string `name`, bool `createDirectory`);`

``bool ok=mail->`createFolder``(const mail::folder *`folder`, bool `createDirectory`);`

std::string errmsg=mail->getErrmsg();

## USAGE

Most mail accounts support the ability to create and delete folders, which are arranged in a tree-like hierarchy. `mail::ACCOUNT::createFolder` creates a new folder. There are two versions of this function.

The first version creates a subfolder of an existing folder, `parentFolder`. `name` is the new folder's name, in the application's character set. If the folder is succesfully created a `mail::folder` object is returned that represents the newly-created folder (the application is responsible for destroying the new `mail::folder` object).

The second version creates a new folder that's specified by an existing `mail::folder` object (which is usually created by mail::ACCOUNT::getFolderFromString(3x) or mail::ACCOUNT::getFolderFromPath(3x)).

NOTE: | `createDirectory` should be set to `true` to create a new folder directory, and `false` for a regular folder. See mail::folder::createSubFolder(3x) for more information.

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

This first `mail::ACCOUNT::createFolder` function returns a NULL pointer if it cannot create the new folder, for some reason; the second `mail::ACCOUNT::createFolder` function returns `false` if it fails.

## SEE ALSO

mail::ACCOUNT::getFolderFromPath(3x), mail::ACCOUNT::getFolderFromString(3x), mail::folder::createSubFolder(3x), mail::setAppCharset(3x).

<<< Previous | Home | Next >>>
mail::ACCOUNT::copyMessagesTo | Up | mail::ACCOUNT::deleteFolder