mail::folder::renameFolder(3x)

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

NAME

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

USAGE

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

RETURN CODES AND CALLBACKS

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

NOTES

134        1. Courier-IMAP
135           http://www.courier-mta.org
136
137
138
139[FIXME: source]                   05/08/2010          MAIL::FOLDER::RENAME(3x)

NAME

SYNOPSIS

USAGE

RETURN CODES AND CALLBACKS

SEE ALSO

NOTES