1MAIL::FOLDER::CREATE(3x)Cone: COnsole Newsreader And EMAIL::FOLDER::CREATE(3x)
2
6 mail::folder::createSubFolder - Create a new folder
7
9 #include <libmail/mail.H>
10 class myCallback : public mail::callback {
13 public:
14 void success(std::string msg);
15 void fail(std::string msg);
16 };
17 class myFolderCallback : public mail::callback::folderlist {
19 public:
20 void success(const std::vector<const mail::folder *> &folders);
21 };
22 mail::folder *folder;
24 folder->createSubFolder(std::string name, bool createDirectory,
26 myFolderCallback &folderCallback,
27 myCallback &callback);
28
30 Most mail accounts support the ability to create and delete folders,
31 which are arranged in a tree-like hierarchy.
32 mail::folder::createSubFolder creates a new folder, as a subfolder of
33 folder (which does not necessarily have to refer the currently open
34 folder; it may be any mail::folder object that´s associated with an
35 active mail::account).
36 Folders may be created in IMAP accounts, and local mail (either mbox or
38 maildir) accounts. Folders cannot be created in POP3 accounts, as this
39 functionality is not supported by the POP3 protocol (this operation
40 will fail).
41 There are two types of folders: folder that contain messages (regular
43 folders), and folders that contain other sub-folders ("folder
44 directories", or "directories" for short). isDirectory specifies
45 whether the new folder is a regular folder, or a folder directory.
46 Note
48 Local maildir-based accounts, and some IMAP servers, are capable of
49 supporting so-called "dual-purpose" folders; folders that contain
50 both messages and other sub-folders. A dual-purpose folder may be
51 created by invoking mail::folder::createSubFolder twice, once with
52 isDirectory set to false; and a second time with isDirectory set to
53 true, specifying the same name both times.
54 name specifies the name of the new folder, in the application´s
56 character set.
57 Note
59 Some mail servers reserve certain characters which cannot be used
60 in folder names. IMAP mail servers use a special character (usually
61 "/" or ".") as a separator between names in a hierarchical folder
62 path. The actual character varies from server to server. An attempt
63 to create/rename a folder whose name includes a reserved character
64 will fail. Different IMAP servers use different hierarchy separator
65 characters. An attempt to create a folder may fail on one IMAP
66 server even if another IMAP server can succesfully create a folder
67 with the same name. This is, unfortunately, a design flaw in the
68 IMAP protocol.
69 Note
71 Maildir folders created by are compatible and can be read by the
72 Courier-IMAP[1] server. Names of maildir folders may contain any
73 character, including the characters ":", "/", ".", "~", and ":".
74 However, if the same folders are exported via IMAP, folders whose
75 name includes these characters may not be readable by some IMAP
76 clients. Even a
77 LibMAIL application may not be able to read one of these folders
81 via IMAP.
82 Note
84 Mbox mail folders created by
85 LibMAIL are mostly compatible and can be exported by IMAP servers
89 that read mbox-formatted mail folders (with some limitations, such
90 as that the same mbox folder cannot be open by
91 LibMAIL and another application at the same time). Names of mbox
95 folders can contain any character, including the characters "/",
96 and "~". However if mbox folders are exported via IMAP, folders
97 whose name includes these characters may not be readable by some
98 IMAP clients.
99
101 The application must wait until callback´s success or fail method is
102 invoked. The success method is invoked when this request is succesfully
103 processed. The fail method is invoked if this request cannot be
104 processed. The application must not destroy callback until either the
105 success or fail method is invoked.
106 Note
108 callback´s fail method may be invoked even after other callback
109 methods were invoked. This indicates that the request was partially
110 completed before the error was encountered.
111 Note
113 The application must not destroy folderCallback until this request
114 fails or succeeds. folderCallback´s success method is invoked just
115 before the callback´s success method.
116 If the folder was succesfully created, the folderCallback.success
118 method receives a vector that contains a single pointer to a
119 mail::folder object. The mail::folder object will refer to the
120 newly-created folder.
121 Note
123 mail::folders are linked to their corresponding mail::accounts. A
124 mail::folder created by one mail::account may not be used with a
125 different mail::folder. All mail::folders created by a
126 mail::account are invalidated when this mail::account object is
127 destroyed. Note that the mail::folder objects are not automatically
128 destroyed; the application is still responsible for destroying any
129 remaining mail::folders, after their a mail::account is destroyed.
130 Note
132 The folderCallback.success method receives a (possibly empty)
133 vector of pointers to mail::folder objects. These objects will be
134 destroyed when folderCallback.success terminates. The application
135 must use mail::folder::clone(3x) to create copies of mail::folder
136 objects it wants to use later.
137 Note
139 Both folderCallback.success and myCallback.success method will be
140 invoked if this request succeeds. folderCallback.success will be
141 invoked before myCallback.success (since by definition this
142 indicates that the request has been completed).
143 Note
145 For some kinds of accounts, mail::folder::readSubFolders(3x) may
146 not enumerate new folder directories until they contain at least
147 one folder. Therefore the recommended process to create a new
148 folder directory is as follows:
149 · Invoke mail::folder::createSubFolder to request the creation of
151 a new folder directory.
152 · In folderCallback.success, use mail::folder::clone(3x) to save
154 a copy of the mail::folder object which refers to the new
155 folder directory.
156 · After the myCallback.success method is invoked, use the saved
158 mail::folder object´s createSubFolder method to create a new
159 folder in the new folder directory.
160
162 mail::folder::clone(3x), mail::folder::create(3x),
163 mail::folder::destroy(3x), mail::folder::readSubFolders(3x),
164 mail::folder::renameFolder(3x).
165
167 1. Courier-IMAP
168 http://www.courier-mta.org
169[FIXME: source] 05/08/2010 MAIL::FOLDER::CREATE(3x)