1Mail::Server::IMAP4::UsUesre(r3)Contributed Perl DocumenMtaaitli:o:nServer::IMAP4::User(3)
2
3
4

NAME

6       Mail::Server::IMAP4::User - manage the folders of one user
7

INHERITANCE

9        Mail::Server::IMAP4::User
10          is a Mail::Box::Manage::User
11          is a Mail::Box::Manager
12          is a Mail::Reporter
13

SYNOPSIS

15        my $mgr = Mail::Server::IMAP4::User->new(...);
16

DESCRIPTION

18       This class adds IMAP protocol features to the normal
19       Mail::Box::Manager.
20
21       Extends "DESCRIPTION" in Mail::Box::Manage::User.
22

METHODS

24       Extends "METHODS" in Mail::Box::Manage::User.
25
26   Constructors
27       Extends "Constructors" in Mail::Box::Manage::User.
28
29       Mail::Server::IMAP4::User->new(%options)
30            -Option             --Defined in             --Default
31             autodetect           Mail::Box::Manager       undef
32             collection_type      Mail::Box::Manage::User  Mail::Box::Collection
33             default_folder_type  Mail::Box::Manager       'mbox'
34             delimiter            Mail::Box::Manage::User  "/"
35             folder_id_type       Mail::Box::Manage::User  Mail::Box::Identity
36             folder_types         Mail::Box::Manager       <all standard types>
37             folderdir            Mail::Box::Manager       [ '.' ]
38             folderdirs           Mail::Box::Manager       <synonym for C<folderdir>>
39             identity             Mail::Box::Manage::User  <required>
40             inbox                Mail::Box::Manage::User  undef
41             index_filename                                $folderdir/index
42             log                  Mail::Reporter           'WARNINGS'
43             topfolder_name       Mail::Box::Manage::User  '='
44             trace                Mail::Reporter           'WARNINGS'
45
46           autodetect => TYPE|ARRAY-OF-TYPES
47           collection_type => CLASS
48           default_folder_type => NAME|CLASS
49           delimiter => STRING
50           folder_id_type => CLASS|OBJECT
51           folder_types => NEW-TYPE | ARRAY-OF-NEW-TYPES
52           folderdir => DIRECTORY
53           folderdirs => [DIRECTORIES]
54           identity => OBJECT
55           inbox => NAME
56           index_filename => FILENAME
57           log => LEVEL
58           topfolder_name => STRING
59           trace => LEVEL
60
61   Attributes
62       Extends "Attributes" in Mail::Box::Manage::User.
63
64       $obj->defaultFolderType()
65           Inherited, see "Attributes" in Mail::Box::Manager
66
67       $obj->folderTypes()
68           Inherited, see "Attributes" in Mail::Box::Manager
69
70       $obj->folderdir()
71           Inherited, see "Attributes" in Mail::Box::Manager
72
73       $obj->identity()
74           Inherited, see "Attributes" in Mail::Box::Manage::User
75
76       $obj->inbox( [$name] )
77           Inherited, see "Attributes" in Mail::Box::Manage::User
78
79       $obj->indexFilename()
80           Returns the filename of the index file.
81
82       $obj->registerType($type, $class, %options)
83           Inherited, see "Attributes" in Mail::Box::Manager
84
85   Manage open folders
86       Extends "Manage open folders" in Mail::Box::Manage::User.
87
88       $obj->close($folder, %options)
89           Inherited, see "Manage open folders" in Mail::Box::Manager
90
91       $obj->closeAllFolders(, %options)
92           Inherited, see "Manage open folders" in Mail::Box::Manager
93
94       $obj->isOpenFolder($folder)
95           Inherited, see "Manage open folders" in Mail::Box::Manager
96
97       $obj->open( [$foldername], %options )
98           Inherited, see "Manage open folders" in Mail::Box::Manager
99
100       $obj->openFolders()
101           Inherited, see "Manage open folders" in Mail::Box::Manager
102
103   Manage existing folders
104       Extends "Manage existing folders" in Mail::Box::Manage::User.
105
106   Manage folders
107       Extends "Manage folders" in Mail::Box::Manage::User.
108
109       $obj->create($name, %options)
110           Creates a new folder with the specified name.  Folder info is
111           returned, which will be very simple.  In the accidental case that
112           the folder already exists, a warning will be issued, and that
113           folder's data returned.
114
115            -Option       --Defined in             --Default
116             create_real    Mail::Box::Manage::User  <true>
117             create_supers  Mail::Box::Manage::User  <false>
118             deleted        Mail::Box::Manage::User  <false>
119             id_options     Mail::Box::Manage::User  []
120
121           create_real => BOOLEAN
122           create_supers => BOOLEAN
123           deleted => BOOLEAN
124           id_options => ARRAY
125       $obj->delete($name, %options)
126           Remove all signs from the folder on the file-system.  Messages
127           still in the folder will be removed.  This method returns a true
128           value when the folder has been removed or not found, so "false"
129           means failure.
130
131           It is also possible to delete a folder using "$folder->delete",
132           which will call this method here.  %options, which are used for
133           some other folder types, will be ignored here: the user's index
134           contains the required details.
135
136            -Option   --Defined in        --Default
137             recursive  Mail::Box::Manager  <folder's default>
138
139           recursive => BOOLEAN
140
141           example: how to delete a folder
142
143            print "no xyz (anymore)\n" if $user->delete('xyz');
144
145       $obj->folder($name)
146           Inherited, see "Manage folders" in Mail::Box::Manage::User
147
148       $obj->folderCollection($name)
149           Inherited, see "Manage folders" in Mail::Box::Manage::User
150
151       $obj->folderInfo($name)
152           Returns a hash with folder information.  In normal circumstances,
153           it is cheap to get these details, because they are cached in an
154           index file, maintained by Mail::Box::Netzwert::UserIndex.
155
156           DO NOT modify the values you find in the hash, because that data
157           may or may not be lost (see Mail::Box::Netzwert::UserIndex
158           subroutine change).
159
160           DO NOT trust on the existence of any field in the info: fields may
161           get renamed, removed, or added over time.  Not all folder indexes
162           will be generated by the same software release.
163
164           example: how to get global info about a folder
165
166            my $info = $user->folderInfo($name); # get info
167
168       $obj->rename($oldname, $newname, %options)
169           Inherited, see "Manage folders" in Mail::Box::Manage::User
170
171       $obj->topfolder()
172           Inherited, see "Manage folders" in Mail::Box::Manage::User
173
174   Move messages to folders
175       Extends "Move messages to folders" in Mail::Box::Manage::User.
176
177       $obj->appendMessage( [$folder|$foldername], $messages, %options )
178           Inherited, see "Move messages to folders" in Mail::Box::Manager
179
180       $obj->copyMessage( [$folder|$foldername], $messages, %options )
181           Inherited, see "Move messages to folders" in Mail::Box::Manager
182
183       $obj->moveMessage( [$folder|$foldername], $messages, %options )
184           Inherited, see "Move messages to folders" in Mail::Box::Manager
185
186   Manage message threads
187       Extends "Manage message threads" in Mail::Box::Manage::User.
188
189       $obj->threads( [$folders], %options )
190           Inherited, see "Manage message threads" in Mail::Box::Manager
191
192   Internals
193       Extends "Internals" in Mail::Box::Manage::User.
194
195       $obj->decodeFolderURL($url)
196           Inherited, see "Internals" in Mail::Box::Manager
197
198       $obj->toBeThreaded($folder, $messages)
199           Inherited, see "Internals" in Mail::Box::Manager
200
201       $obj->toBeUnthreaded($folder, $messages)
202           Inherited, see "Internals" in Mail::Box::Manager
203
204   Error handling
205       Extends "Error handling" in Mail::Box::Manage::User.
206
207       $obj->AUTOLOAD()
208           Inherited, see "Error handling" in Mail::Reporter
209
210       $obj->addReport($object)
211           Inherited, see "Error handling" in Mail::Reporter
212
213       $obj->defaultTrace( [$level]|[$loglevel, $tracelevel]|[$level,
214       $callback] )
215       Mail::Server::IMAP4::User->defaultTrace( [$level]|[$loglevel,
216       $tracelevel]|[$level, $callback] )
217           Inherited, see "Error handling" in Mail::Reporter
218
219       $obj->errors()
220           Inherited, see "Error handling" in Mail::Reporter
221
222       $obj->log( [$level, [$strings]] )
223       Mail::Server::IMAP4::User->log( [$level, [$strings]] )
224           Inherited, see "Error handling" in Mail::Reporter
225
226       $obj->logPriority($level)
227       Mail::Server::IMAP4::User->logPriority($level)
228           Inherited, see "Error handling" in Mail::Reporter
229
230       $obj->logSettings()
231           Inherited, see "Error handling" in Mail::Reporter
232
233       $obj->notImplemented()
234           Inherited, see "Error handling" in Mail::Reporter
235
236       $obj->report( [$level] )
237           Inherited, see "Error handling" in Mail::Reporter
238
239       $obj->reportAll( [$level] )
240           Inherited, see "Error handling" in Mail::Reporter
241
242       $obj->trace( [$level] )
243           Inherited, see "Error handling" in Mail::Reporter
244
245       $obj->warnings()
246           Inherited, see "Error handling" in Mail::Reporter
247
248   Cleanup
249       Extends "Cleanup" in Mail::Box::Manage::User.
250
251       $obj->DESTROY()
252           Inherited, see "Cleanup" in Mail::Reporter
253

DETAILS

255       Extends "DETAILS" in Mail::Box::Manage::User.
256

DIAGNOSTICS

258       Error: Cannot create folder directory $dir: $!
259       Error: Cannot rename $name to $new: higher levels missing
260           Unless you set create(create_supers), all higher level folders must
261           exist before this new one can be created.
262
263       Error: Cannot write name for folder in $file: $!
264       Error: Failed writing folder name to $file: $!
265       Warning: Folder $name already exists, creation skipped
266       Error: Folder $name is already open.
267           You cannot ask the manager for a folder which is already open. In
268           some older releases (before MailBox 2.049), this was permitted, but
269           then behaviour changed, because many nasty side-effects are to be
270           expected.  For instance, an Mail::Box::update() on one folder
271           handle would influence the second, probably unexpectedly.
272
273       Error: Folder $name is not a Mail::Box; cannot add a message.
274           The folder where the message should be appended to is an object
275           which is not a folder type which extends Mail::Box.  Probably, it
276           is not a folder at all.
277
278       Warning: Folder does not exist, failed opening $type folder $name.
279           The folder does not exist and creating is not permitted (see
280           open(create)) or did not succeed.  When you do not have sufficient
281           access rights to the folder (for instance wrong password for POP3),
282           this warning will be produced as well.
283
284           The manager tried to open a folder of the specified type.  It may
285           help to explicitly state the type of your folder with the "type"
286           option.  There will probably be another warning or error message
287           which is related to this report and provides more details about its
288           cause.  You may also have a look at new(autodetect) and
289           new(folder_types).
290
291       Warning: Folder type $type is unknown, using autodetect.
292           The specified folder type (see open(type), possibly derived from
293           the folder name when specified as url) is not known to the manager.
294           This may mean that you forgot to require the Mail::Box extension
295           which implements this folder type, but probably it is a typo.
296           Usually, the manager is able to figure-out which type to use by
297           itself.
298
299       Error: Illegal folder URL '$url'.
300           The folder name was specified as URL, but not according to the
301           syntax.  See decodeFolderURL() for an description of the syntax.
302
303       Error: No foldername specified to open.
304           open() needs a folder name as first argument (before the list of
305           options), or with the "folder" option within the list.  If no name
306           was found, the MAIL environment variable is checked.  When even
307           that does not result in a usable folder, then this error is
308           produced.  The error may be caused by an accidental odd-length
309           option list.
310
311       Error: Package $package does not implement $method.
312           Fatal error: the specific package (or one of its superclasses) does
313           not implement this method where it should. This message means that
314           some other related classes do implement this method however the
315           class at hand does not.  Probably you should investigate this and
316           probably inform the author of the package.
317
318       Error: Unable to remove folder $dir
319       Error: Use appendMessage() to add messages which are not in a folder.
320           You do not need to copy this message into the folder, because you
321           do not share the message between folders.
322
323       Warning: Use moveMessage() or copyMessage() to move between open
324       folders.
325           The message is already part of a folder, and now it should be
326           appended to a different folder.  You need to decide between copy or
327           move, which both will clone the message (not the body, because they
328           are immutable).
329
330       Warning: Will never create a folder $name without having write access.
331           You have set open(create), but only want to read the folder.
332           Create is only useful for folders which have write or append access
333           modes (see Mail::Box::new(access)).
334

SEE ALSO

336       This module is part of Mail-Box-IMAP4 distribution version 3.008, built
337       on August 09, 2023. Website: http://perl.overmeer.net/CPAN/
338

LICENSE

340       Copyrights 2001-2023 by [Mark Overmeer]. For other contributors see
341       ChangeLog.
342
343       This program is free software; you can redistribute it and/or modify it
344       under the same terms as Perl itself.  See http://dev.perl.org/licenses/
345
346
347
348perl v5.38.0                      2023-08-21      Mail::Server::IMAP4::User(3)
Impressum