1Mail::Box::Manage::UserU(s3e)r Contributed Perl DocumentaMtaiioln::Box::Manage::User(3)
2
3
4

NAME

6       Mail::Box::Manage::User - manage the folders of a user
7

INHERITANCE

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

SYNOPSIS

17        use Mail::Box::Manage::User;
18        use User::Identity;
19
20        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
27        my $inbox   = $user->open($user->inbox);
28        my $top     = $user->topfolder;
29

DESCRIPTION

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
36       Extends "DESCRIPTION" in Mail::Box::Manager.
37

METHODS

39       Extends "METHODS" in Mail::Box::Manager.
40
41   Constructors
42       Extends "Constructors" in Mail::Box::Manager.
43
44       Mail::Box::Manage::User->new($args)
45           Use new(default_folder_type) to explicitly state which kind of
46           folders you use.
47
48            -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
63           autodetect => TYPE|ARRAY-OF-TYPES
64           collection_type => CLASS
65             Subfolders grouped together.
66
67           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
72           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
82             The smallest identity that will do: "my $id =
83             User::Identity->new('myname')"
84
85           inbox => NAME
86             The name of the user's inbox.
87
88           log => LEVEL
89           topfolder_name => STRING
90           trace => LEVEL
91
92   Attributes
93       Extends "Attributes" in Mail::Box::Manager.
94
95       $obj->defaultFolderType()
96           Inherited, see "Attributes" in Mail::Box::Manager
97
98       $obj->folderTypes()
99           Inherited, see "Attributes" in Mail::Box::Manager
100
101       $obj->folderdir()
102           Inherited, see "Attributes" in Mail::Box::Manager
103
104       $obj->identity()
105           Returns a User::Identity object.
106
107       $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
113       $obj->registerType($type, $class, %options)
114           Inherited, see "Attributes" in Mail::Box::Manager
115
116   Manage open folders
117       Extends "Manage open folders" in Mail::Box::Manager.
118
119       $obj->close($folder, %options)
120           Inherited, see "Manage open folders" in Mail::Box::Manager
121
122       $obj->closeAllFolders(, %options)
123           Inherited, see "Manage open folders" in Mail::Box::Manager
124
125       $obj->isOpenFolder($folder)
126           Inherited, see "Manage open folders" in Mail::Box::Manager
127
128       $obj->open( [$foldername], %options )
129           Inherited, see "Manage open folders" in Mail::Box::Manager
130
131       $obj->openFolders()
132           Inherited, see "Manage open folders" in Mail::Box::Manager
133
134   Manage existing folders
135       Extends "Manage existing folders" in Mail::Box::Manager.
136
137   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
143           In the accidental case that the folder already exists, a warning
144           will be issued, and an empty list/undef returned.
145
146           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
150            -Option       --Default
151             create_real    <true>
152             create_supers  <false>
153             deleted        <false>
154             id_options     []
155
156           create_real => BOOLEAN
157             When this option is false, the pysical folder will not be
158             created, but only the administration is updated.
159
160           create_supers => BOOLEAN
161             When you create a folder where upper hierarchy level are missing,
162             they will be created as well.
163
164           deleted => BOOLEAN
165             The folder starts as deleted.
166
167           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
171       $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
177           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
182            -Option   --Defined in        --Default
183             recursive  Mail::Box::Manager  <folder's default>
184
185           recursive => BOOLEAN
186
187           example: how to delete a folder
188
189            print "no xyz (anymore)\n" if $user->delete('xyz');
190
191       $obj->folder($name)
192           Returns the folder description, a Mail::Box::Identity.
193
194       $obj->folderCollection($name)
195           Returns a pair: the folder collection (Mail::Box::Collection) and
196           the base name of $name.
197
198       $obj->rename($oldname, $newname, %options)
199           Rename the folder with name $oldname to $newname.  Both names are
200           full pathnames.
201
202            -Option       --Default
203             create_supers  <false>
204
205           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
210       $obj->topfolder()
211           Returns the top folder of the user's mailbox storage.
212
213   Move messages to folders
214       Extends "Move messages to folders" in Mail::Box::Manager.
215
216       $obj->appendMessage( [$folder|$foldername], $messages, %options )
217           Inherited, see "Move messages to folders" in Mail::Box::Manager
218
219       $obj->copyMessage( [$folder|$foldername], $messages, %options )
220           Inherited, see "Move messages to folders" in Mail::Box::Manager
221
222       $obj->moveMessage( [$folder|$foldername], $messages, %options )
223           Inherited, see "Move messages to folders" in Mail::Box::Manager
224
225   Manage message threads
226       Extends "Manage message threads" in Mail::Box::Manager.
227
228       $obj->threads( [$folders], %options )
229           Inherited, see "Manage message threads" in Mail::Box::Manager
230
231   Internals
232       Extends "Internals" in Mail::Box::Manager.
233
234       $obj->decodeFolderURL($url)
235           Inherited, see "Internals" in Mail::Box::Manager
236
237       $obj->toBeThreaded($folder, $messages)
238           Inherited, see "Internals" in Mail::Box::Manager
239
240       $obj->toBeUnthreaded($folder, $messages)
241           Inherited, see "Internals" in Mail::Box::Manager
242
243   Error handling
244       Extends "Error handling" in Mail::Box::Manager.
245
246       $obj->AUTOLOAD()
247           Inherited, see "Error handling" in Mail::Reporter
248
249       $obj->addReport($object)
250           Inherited, see "Error handling" in Mail::Reporter
251
252       $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
258       $obj->errors()
259           Inherited, see "Error handling" in Mail::Reporter
260
261       $obj->log( [$level, [$strings]] )
262       Mail::Box::Manage::User->log( [$level, [$strings]] )
263           Inherited, see "Error handling" in Mail::Reporter
264
265       $obj->logPriority($level)
266       Mail::Box::Manage::User->logPriority($level)
267           Inherited, see "Error handling" in Mail::Reporter
268
269       $obj->logSettings()
270           Inherited, see "Error handling" in Mail::Reporter
271
272       $obj->notImplemented()
273           Inherited, see "Error handling" in Mail::Reporter
274
275       $obj->report( [$level] )
276           Inherited, see "Error handling" in Mail::Reporter
277
278       $obj->reportAll( [$level] )
279           Inherited, see "Error handling" in Mail::Reporter
280
281       $obj->trace( [$level] )
282           Inherited, see "Error handling" in Mail::Reporter
283
284       $obj->warnings()
285           Inherited, see "Error handling" in Mail::Reporter
286
287   Cleanup
288       Extends "Cleanup" in Mail::Box::Manager.
289
290       $obj->DESTROY()
291           Inherited, see "Cleanup" in Mail::Reporter
292

DETAILS

294       Extends "DETAILS" in Mail::Box::Manager.
295

DIAGNOSTICS

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
301       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
305       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
312       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
317       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
323           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
330       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
338       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
342       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
350       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
357       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
362       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
369       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

SEE ALSO

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

LICENSE

379       Copyrights 2001-2023 by [Mark Overmeer]. For other contributors see
380       ChangeLog.
381
382       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/
384
385
386
387perl v5.38.0                      2023-07-24        Mail::Box::Manage::User(3)
Impressum