1Mail::Box::Manage::UserU(s3e)r Contributed Perl DocumentaMtaiioln::Box::Manage::User(3)
2
6 Mail::Box::Manage::User - manage the folders of a user
7
9 Mail::Box::Manage::User
10 is a Mail::Box::Manager
11 is a Mail::Reporter
12 Mail::Box::Manage::User is extended by
14 Mail::Server::IMAP4::User
15
17 use Mail::Box::Manage::User;
18 use User::Identity;
19 my $id = User::Identity->new(...);
21 my $user = Mail::Box::Manage::User->new
22 ( identity => $id
23 , folderdir => "$ENV{HOME}/Mail"
24 , inbox => $ENV{MAIL}
25 );
26 my $inbox = $user->open($user->inbox);
28 my $top = $user->topfolder;
29
31 Where the Mail::Box::Manager takes care of some set of open folder,
32 this extension will add knowledge about some related person. At the
33 same time, it will try to cache some information about that person's
34 folder files.
35 Extends "DESCRIPTION" in Mail::Box::Manager.
37
39 Extends "METHODS" in Mail::Box::Manager.
40 Constructors
42 Extends "Constructors" in Mail::Box::Manager.
43 Mail::Box::Manage::User->new($args)
45 Use new(default_folder_type) to explicitly state which kind of
46 folders you use.
47 -Option --Defined in --Default
49 autodetect Mail::Box::Manager undef
50 collection_type Mail::Box::Collection
51 default_folder_type Mail::Box::Manager 'mbox'
52 delimiter "/"
53 folder_id_type Mail::Box::Identity
54 folder_types Mail::Box::Manager <all standard types>
55 folderdir Mail::Box::Manager [ '.' ]
56 folderdirs Mail::Box::Manager <synonym for C<folderdir>>
57 identity <required>
58 inbox undef
59 log Mail::Reporter 'WARNINGS'
60 topfolder_name '='
61 trace Mail::Reporter 'WARNINGS'
62 autodetect => TYPE|ARRAY-OF-TYPES
64 collection_type => CLASS
65 Subfolders grouped together.
66 default_folder_type => NAME|CLASS
68 delimiter => STRING
69 The separator used in folder names. This doesn't need to be the
70 same as your directory system is using.
71 folder_id_type => CLASS|OBJECT
73 folder_types => NEW-TYPE | ARRAY-OF-NEW-TYPES
74 folderdir => DIRECTORY
75 folderdirs => [DIRECTORIES]
76 identity => OBJECT
77 The main difference between the Mail::Box::Manager and this
78 class, is the concept of some person (or virtual person) who's
79 files are being administered by this object. The OBJECT is an
80 User::Identity.
81 The smallest identity that will do: "my $id =
83 User::Identity->new('myname')"
84 inbox => NAME
86 The name of the user's inbox.
87 log => LEVEL
89 topfolder_name => STRING
90 trace => LEVEL
91 Attributes
93 Extends "Attributes" in Mail::Box::Manager.
94 $obj->defaultFolderType()
96 Inherited, see "Attributes" in Mail::Box::Manager
97 $obj->folderTypes()
99 Inherited, see "Attributes" in Mail::Box::Manager
100 $obj->folderdir()
102 Inherited, see "Attributes" in Mail::Box::Manager
103 $obj->identity()
105 Returns a User::Identity object.
106 $obj->inbox( [$name] )
108 (Set and) get the $name of the mailbox which is considered the
109 folder for incoming mail. In many protocols, this folder is
110 handled separately. For instance in IMAP this is the only case-
111 insensitive folder name.
112 $obj->registerType($type, $class, %options)
114 Inherited, see "Attributes" in Mail::Box::Manager
115 Manage open folders
117 Extends "Manage open folders" in Mail::Box::Manager.
118 $obj->close($folder, %options)
120 Inherited, see "Manage open folders" in Mail::Box::Manager
121 $obj->closeAllFolders(, %options)
123 Inherited, see "Manage open folders" in Mail::Box::Manager
124 $obj->isOpenFolder($folder)
126 Inherited, see "Manage open folders" in Mail::Box::Manager
127 $obj->open( [$foldername], %options )
129 Inherited, see "Manage open folders" in Mail::Box::Manager
130 $obj->openFolders()
132 Inherited, see "Manage open folders" in Mail::Box::Manager
133 Manage existing folders
135 Extends "Manage existing folders" in Mail::Box::Manager.
136 Manage folders
138 $obj->create($name, %options)
139 Creates a new folder with the specified name. An folder's
140 administrative structure (Mail::Box::Identity) is returned, but the
141 folder is not opened.
142 In the accidental case that the folder already exists, a warning
144 will be issued, and an empty list/undef returned.
145 The %options are passed to Mail::Box::create() of your default
147 folder type, except for the options intended for this method
148 itself.
149 -Option --Default
151 create_real <true>
152 create_supers <false>
153 deleted <false>
154 id_options []
155 create_real => BOOLEAN
157 When this option is false, the pysical folder will not be
158 created, but only the administration is updated.
159 create_supers => BOOLEAN
161 When you create a folder where upper hierarchy level are missing,
162 they will be created as well.
163 deleted => BOOLEAN
165 The folder starts as deleted.
166 id_options => ARRAY
168 Values passed to the instantiated Mail::Box::Identity. That
169 object is very picky about the initiation values it accepts.
170 $obj->delete($name)
172 Remove all signs from the folder on the file-system. Messages
173 still in the folder will be removed. This method returns a true
174 value when the folder has been removed or not found, so "false"
175 means failure.
176 It is also possible to delete a folder using "$folder->delete",
178 which will call this method here. OPTIONS, which are used for some
179 other folder types, will be ignored here: the user's index contains
180 the required details.
181 -Option --Defined in --Default
183 recursive Mail::Box::Manager <folder's default>
184 recursive => BOOLEAN
186 example: how to delete a folder
188 print "no xyz (anymore)\n" if $user->delete('xyz');
190 $obj->folder($name)
192 Returns the folder description, a Mail::Box::Identity.
193 $obj->folderCollection($name)
195 Returns a pair: the folder collection (Mail::Box::Collection) and
196 the base name of $name.
197 $obj->rename($oldname, $newname, %options)
199 Rename the folder with name $oldname to $newname. Both names are
200 full pathnames.
201 -Option --Default
203 create_supers <false>
204 create_supers => BOOLEAN
206 When you rename a folder to a place where upper hierarchy levels
207 are missing, they will get be defined, but with the deleted flag
208 set.
209 $obj->topfolder()
211 Returns the top folder of the user's mailbox storage.
212 Move messages to folders
214 Extends "Move messages to folders" in Mail::Box::Manager.
215 $obj->appendMessage( [$folder|$foldername], $messages, %options )
217 Inherited, see "Move messages to folders" in Mail::Box::Manager
218 $obj->copyMessage( [$folder|$foldername], $messages, %options )
220 Inherited, see "Move messages to folders" in Mail::Box::Manager
221 $obj->moveMessage( [$folder|$foldername], $messages, %options )
223 Inherited, see "Move messages to folders" in Mail::Box::Manager
224 Manage message threads
226 Extends "Manage message threads" in Mail::Box::Manager.
227 $obj->threads( [$folders], %options )
229 Inherited, see "Manage message threads" in Mail::Box::Manager
230 Internals
232 Extends "Internals" in Mail::Box::Manager.
233 $obj->decodeFolderURL($url)
235 Inherited, see "Internals" in Mail::Box::Manager
236 $obj->toBeThreaded($folder, $messages)
238 Inherited, see "Internals" in Mail::Box::Manager
239 $obj->toBeUnthreaded($folder, $messages)
241 Inherited, see "Internals" in Mail::Box::Manager
242 Error handling
244 Extends "Error handling" in Mail::Box::Manager.
245 $obj->AUTOLOAD()
247 Inherited, see "Error handling" in Mail::Reporter
248 $obj->addReport($object)
250 Inherited, see "Error handling" in Mail::Reporter
251 $obj->defaultTrace( [$level]|[$loglevel, $tracelevel]|[$level,
253 $callback] )
254 Mail::Box::Manage::User->defaultTrace( [$level]|[$loglevel,
255 $tracelevel]|[$level, $callback] )
256 Inherited, see "Error handling" in Mail::Reporter
257 $obj->errors()
259 Inherited, see "Error handling" in Mail::Reporter
260 $obj->log( [$level, [$strings]] )
262 Mail::Box::Manage::User->log( [$level, [$strings]] )
263 Inherited, see "Error handling" in Mail::Reporter
264 $obj->logPriority($level)
266 Mail::Box::Manage::User->logPriority($level)
267 Inherited, see "Error handling" in Mail::Reporter
268 $obj->logSettings()
270 Inherited, see "Error handling" in Mail::Reporter
271 $obj->notImplemented()
273 Inherited, see "Error handling" in Mail::Reporter
274 $obj->report( [$level] )
276 Inherited, see "Error handling" in Mail::Reporter
277 $obj->reportAll( [$level] )
279 Inherited, see "Error handling" in Mail::Reporter
280 $obj->trace( [$level] )
282 Inherited, see "Error handling" in Mail::Reporter
283 $obj->warnings()
285 Inherited, see "Error handling" in Mail::Reporter
286 Cleanup
288 Extends "Cleanup" in Mail::Box::Manager.
289 $obj->DESTROY()
291 Inherited, see "Cleanup" in Mail::Reporter
292
294 Extends "DETAILS" in Mail::Box::Manager.
295
297 Error: Cannot create $name: higher levels missing
298 Unless you set create(create_supers), all higher level folders must
299 exist before this new one can be created.
300 Error: Cannot rename $name to $new: higher levels missing
302 Unless you set create(create_supers), all higher level folders must
303 exist before this new one can be created.
304 Error: Folder $name is already open.
306 You cannot ask the manager for a folder which is already open. In
307 some older releases (before MailBox 2.049), this was permitted, but
308 then behaviour changed, because many nasty side-effects are to be
309 expected. For instance, an Mail::Box::update() on one folder
310 handle would influence the second, probably unexpectedly.
311 Error: Folder $name is not a Mail::Box; cannot add a message.
313 The folder where the message should be appended to is an object
314 which is not a folder type which extends Mail::Box. Probably, it
315 is not a folder at all.
316 Warning: Folder does not exist, failed opening $type folder $name.
318 The folder does not exist and creating is not permitted (see
319 open(create)) or did not succeed. When you do not have sufficient
320 access rights to the folder (for instance wrong password for POP3),
321 this warning will be produced as well.
322 The manager tried to open a folder of the specified type. It may
324 help to explicitly state the type of your folder with the "type"
325 option. There will probably be another warning or error message
326 which is related to this report and provides more details about its
327 cause. You may also have a look at new(autodetect) and
328 new(folder_types).
329 Warning: Folder type $type is unknown, using autodetect.
331 The specified folder type (see open(type), possibly derived from
332 the folder name when specified as url) is not known to the manager.
333 This may mean that you forgot to require the Mail::Box extension
334 which implements this folder type, but probably it is a typo.
335 Usually, the manager is able to figure-out which type to use by
336 itself.
337 Error: Illegal folder URL '$url'.
339 The folder name was specified as URL, but not according to the
340 syntax. See decodeFolderURL() for an description of the syntax.
341 Error: No foldername specified to open.
343 open() needs a folder name as first argument (before the list of
344 options), or with the "folder" option within the list. If no name
345 was found, the MAIL environment variable is checked. When even
346 that does not result in a usable folder, then this error is
347 produced. The error may be caused by an accidental odd-length
348 option list.
349 Error: Package $package does not implement $method.
351 Fatal error: the specific package (or one of its superclasses) does
352 not implement this method where it should. This message means that
353 some other related classes do implement this method however the
354 class at hand does not. Probably you should investigate this and
355 probably inform the author of the package.
356 Error: Unable to remove folder $dir
358 Error: Use appendMessage() to add messages which are not in a folder.
359 You do not need to copy this message into the folder, because you
360 do not share the message between folders.
361 Warning: Use moveMessage() or copyMessage() to move between open
363 folders.
364 The message is already part of a folder, and now it should be
365 appended to a different folder. You need to decide between copy or
366 move, which both will clone the message (not the body, because they
367 are immutable).
368 Warning: Will never create a folder $name without having write access.
370 You have set open(create), but only want to read the folder.
371 Create is only useful for folders which have write or append access
372 modes (see Mail::Box::new(access)).
373
375 This module is part of Mail-Box distribution version 3.010, built on
376 July 18, 2023. Website: http://perl.overmeer.net/CPAN/
377
379 Copyrights 2001-2023 by [Mark Overmeer]. For other contributors see
380 ChangeLog.
381 This program is free software; you can redistribute it and/or modify it
383 under the same terms as Perl itself. See http://dev.perl.org/licenses/
384perl v5.38.0 2023-07-24 Mail::Box::Manage::User(3)