mail::folder::createSubFolder(3x)

1mail::folder::createSubFmoalidle:r:(f3oxl)der Native APImarielf:e:rfeonlcdeer::createSubFolder(3x)
2
3
4

NAME

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

SYNOPSIS

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

USAGE

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

RETURN CODES AND CALLBACKS

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

NAME

SYNOPSIS

USAGE

RETURN CODES AND CALLBACKS

SEE ALSO