mail::folder::createSubFolder(3x)

1        Cone©
2
3MAIL::FOLDER::CREATE(3x)Cone: COnsole Newsreader And EMAIL::FOLDER::CREATE(3x)
4
5
6

NAME

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

SYNOPSIS

11       #include <libmail/mail.H>
12
13
14       class myCallback : public mail::callback {
15       public:
16           void success(std::string msg);
17           void fail(std::string msg);
18       };
19
20       class myFolderCallback : public mail::callback::folderlist {
21       public:
22           void success(const std::vector<const mail::folder *> &folders);
23       };
24
25       mail::folder *folder;
26
27       folder->createSubFolder(std::string name, bool createDirectory,
28                               myFolderCallback &folderCallback,
29                               myCallback &callback);
30

USAGE

32       Most mail accounts support the ability to create and delete folders,
33       which are arranged in a tree-like hierarchy.
34       mail::folder::createSubFolder creates a new folder, as a subfolder of
35       folder (which does not necessarily have to refer the currently open
36       folder; it may be any mail::folder object that's associated with an
37       active mail::account).
38
39       Folders may be created in IMAP accounts, and local mail (either mbox or
40       maildir) accounts. Folders cannot be created in POP3 accounts, as this
41       functionality is not supported by the POP3 protocol (this operation
42       will fail).
43
44       There are two types of folders: folder that contain messages (regular
45       folders), and folders that contain other sub-folders ("folder
46       directories", or "directories" for short).  isDirectory specifies
47       whether the new folder is a regular folder, or a folder directory.
48
49           Note
50           Local maildir-based accounts, and some IMAP servers, are capable of
51           supporting so-called "dual-purpose" folders; folders that contain
52           both messages and other sub-folders. A dual-purpose folder may be
53           created by invoking mail::folder::createSubFolder twice, once with
54           isDirectory set to false; and a second time with isDirectory set to
55           true, specifying the same name both times.
56
57       name specifies the name of the new folder, in the application's
58       character set.
59
60           Note
61           Some mail servers reserve certain characters which cannot be used
62           in folder names. IMAP mail servers use a special character (usually
63           "/" or ".") as a separator between names in a hierarchical folder
64           path. The actual character varies from server to server. An attempt
65           to create/rename a folder whose name includes a reserved character
66           will fail. Different IMAP servers use different hierarchy separator
67           characters. An attempt to create a folder may fail on one IMAP
68           server even if another IMAP server can succesfully create a folder
69           with the same name. This is, unfortunately, a design flaw in the
70           IMAP protocol.
71
72           Note
73           Maildir folders created by are compatible and can be read by the
74           Courier-IMAP[1] server. Names of maildir folders may contain any
75           character, including the characters ":", "/", ".", "~", and ":".
76           However, if the same folders are exported via IMAP, folders whose
77           name includes these characters may not be readable by some IMAP
78           clients. Even a LibMAIL application may not be able to read one of
79           these folders via IMAP.
80
81           Note
82           Mbox mail folders created by LibMAIL are mostly compatible and can
83           be exported by IMAP servers that read mbox-formatted mail folders
84           (with some limitations, such as that the same mbox folder cannot be
85           open by LibMAIL and another application at the same time). Names of
86           mbox folders can contain any character, including the characters
87           "/", and "~". However if mbox folders are exported via IMAP,
88           folders whose name includes these characters may not be readable by
89           some IMAP clients.
90

RETURN CODES AND CALLBACKS

92       The application must wait until callback's success or fail method is
93       invoked. The success method is invoked when this request is succesfully
94       processed. The fail method is invoked if this request cannot be
95       processed. The application must not destroy callback until either the
96       success or fail method is invoked.
97
98           Note
99           callback's fail method may be invoked even after other callback
100           methods were invoked. This indicates that the request was partially
101           completed before the error was encountered.
102
103           Note
104           The application must not destroy folderCallback until this request
105           fails or succeeds.  folderCallback's success method is invoked just
106           before the callback's success method.
107
108       If the folder was succesfully created, the folderCallback.success
109       method receives a vector that contains a single pointer to a
110       mail::folder object. The mail::folder object will refer to the
111       newly-created folder.
112
113           Note
114           mail::folders are linked to their corresponding mail::accounts. A
115           mail::folder created by one mail::account may not be used with a
116           different mail::folder. All mail::folders created by a
117           mail::account are invalidated when this mail::account object is
118           destroyed. Note that the mail::folder objects are not automatically
119           destroyed; the application is still responsible for destroying any
120           remaining mail::folders, after their a mail::account is destroyed.
121
122           Note
123           The folderCallback.success method receives a (possibly empty)
124           vector of pointers to mail::folder objects. These objects will be
125           destroyed when folderCallback.success terminates. The application
126           must use mail::folder::clone(3x) to create copies of mail::folder
127           objects it wants to use later.
128
129           Note
130           Both folderCallback.success and myCallback.success method will be
131           invoked if this request succeeds.  folderCallback.success will be
132           invoked before myCallback.success (since by definition this
133           indicates that the request has been completed).
134
135           Note
136           For some kinds of accounts, mail::folder::readSubFolders(3x) may
137           not enumerate new folder directories until they contain at least
138           one folder. Therefore the recommended process to create a new
139           folder directory is as follows:
140
141           ·   Invoke mail::folder::createSubFolder to request the creation of
142               a new folder directory.
143
144           ·   In folderCallback.success, use mail::folder::clone(3x) to save
145               a copy of the mail::folder object which refers to the new
146               folder directory.
147
148           ·   After the myCallback.success method is invoked, use the saved
149               mail::folder object's createSubFolder method to create a new
150               folder in the new folder directory.
151

AUTHOR

158       Sam Varshavchik
159

NOTES

161        1. Courier-IMAP
162           http://www.courier-mta.org
163
164
165
166Cone©                             08/25/2016          MAIL::FOLDER::CREATE(3x)

NAME

SYNOPSIS

USAGE

RETURN CODES AND CALLBACKS

SEE ALSO

AUTHOR

NOTES