mail::folder::renameFolder(3x)

1mail::folder::renameFoldmeari(l3:x:)folder Native API remfaeirle:n:cfeolder::renameFolder(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
26
27       folder->renameFolder  (const mail::folder *newParent, std::string name,
28       myFolderCallback &folderCallback, myCallback &callback);
29

USAGE

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

RETURN CODES AND CALLBACKS

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

NAME

SYNOPSIS

USAGE

RETURN CODES AND CALLBACKS

SEE ALSO