mail::folder::renameFolder(3x)

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

NAME

8       mail::folder::renameFolder - Rename a 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->renameFolder(const mail::folder *newParent, std::string name,
28                            myFolderCallback &folderCallback,
29                            myCallback &callback);
30

USAGE

32       This function renames an existing folder.  folder is an existing folder
33       or a folder directory (see mail::folder::createSubFolder(3x) for more
34       information on folders and folder directories).  newParent, if not
35       NULL, specifies the new parent folder directory. A NULL newParent
36       specifies that the folder should be be moved to the top level of the
37       mail account's folder hierarchy.
38
39       name specifies the new name of the folder, in the application's
40       character set.
41
42           Note
43           Some mail servers reserve certain characters which cannot be used
44           in folder names. IMAP mail servers use a special character (usually
45           "/" or ".") as a separator between names in a hierarchical folder
46           path. The actual character varies from server to server. An attempt
47           to create/rename a folder whose name includes a reserved character
48           will fail. Different IMAP servers use different hierarchy separator
49           characters. An attempt to create a folder may fail on one IMAP
50           server even if another IMAP server can succesfully create a folder
51           with the same name. This is, unfortunately, a design flaw in the
52           IMAP protocol.
53
54           Note
55           Maildir folders created by are compatible and can be read by the
56           Courier-IMAP[1] server. Names of maildir folders may contain any
57           character, including the characters ":", "/", ".", "~", and ":".
58           However, if the same folders are exported via IMAP, folders whose
59           name includes these characters may not be readable by some IMAP
60           clients. Even a LibMAIL application may not be able to read one of
61           these folders via IMAP.
62
63           Note
64           Mbox mail folders created by LibMAIL are mostly compatible and can
65           be exported by IMAP servers that read mbox-formatted mail folders
66           (with some limitations, such as that the same mbox folder cannot be
67           open by LibMAIL and another application at the same time). Names of
68           mbox folders can contain any character, including the characters
69           "/", and "~". However if mbox folders are exported via IMAP,
70           folders whose name includes these characters may not be readable by
71           some IMAP clients.
72

RETURN CODES AND CALLBACKS

74       The application must wait until callback's success or fail method is
75       invoked. The success method is invoked when this request is succesfully
76       processed. The fail method is invoked if this request cannot be
77       processed. The application must not destroy callback until either the
78       success or fail method is invoked.
79
80           Note
81           callback's fail method may be invoked even after other callback
82           methods were invoked. This indicates that the request was partially
83           completed before the error was encountered.
84
85           Note
86           The application must not destroy folderCallback until this request
87           fails or succeeds.  folderCallback's success method is invoked just
88           before the callback's success method.
89
90       If the folder was succesfully renamed, the folderCallback.success
91       method receives a vector that contains a single pointer to a
92       mail::folder object that refers to this folder under its new name. The
93       existing mail::folder object is no longer valid, and should be
94       destroyed. The new mail::folder object should now be used to refer to
95       this folder.
96
97           Note
98           mail::folders are linked to their corresponding mail::accounts. A
99           mail::folder created by one mail::account may not be used with a
100           different mail::folder. All mail::folders created by a
101           mail::account are invalidated when this mail::account object is
102           destroyed. Note that the mail::folder objects are not automatically
103           destroyed; the application is still responsible for destroying any
104           remaining mail::folders, after their a mail::account is destroyed.
105
106           Note
107           The folderCallback.success method receives a (possibly empty)
108           vector of pointers to mail::folder objects. These objects will be
109           destroyed when folderCallback.success terminates. The application
110           must use mail::folder::clone(3x) to create copies of mail::folder
111           objects it wants to use later.
112
113           Note
114           Both folderCallback.success and myCallback.success method will be
115           invoked if this request succeeds.  folderCallback.success will be
116           invoked before myCallback.success (since by definition this
117           indicates that the request has been completed).
118

AUTHOR

125       Sam Varshavchik
126

NOTES

128        1. Courier-IMAP
129           http://www.courier-mta.org
130
131
132
133Cone©                             08/25/2016          MAIL::FOLDER::RENAME(3x)

NAME

SYNOPSIS

USAGE

RETURN CODES AND CALLBACKS

SEE ALSO

AUTHOR

NOTES