Mail::Box::Manage::User(3pm)

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

SYNOPSIS

14        use Mail::Box::Manage::User;
15        use User::Identity;
16
17        my $id      = User::Identity->new(...);
18        my $user    = Mail::Box::Manage::User->new
19          ( identity  => $id
20          , folderdir => "$ENV{HOME}/Mail"
21          , inbox     => $ENV{MAIL}
22          );
23
24        my $inbox   = $user->open($user->inbox);
25        my $top     = $user->topfolder;
26

DESCRIPTION

28       Where the Mail::Box::Manager takes care of some set of open folder,
29       this extension will add knowledge about some related person.  At the
30       same time, it will try to cache some information about that person's
31       folder files.
32

METHODS

34       Constructors
35
36       Mail::Box::Manage::User->new(ARGS)
37
38           Use new(default_folder_type) to explicitly state which kind of
39           folders you use.
40
41            Option             --Defined in     --Default
42            autodetect           Mail::Box::Manager  undef
43            collection_type                       Mail::Box::Collection
44            default_folder_type  Mail::Box::Manager  'mbox'
45            delimiter                             "/"
46            folder_id_type                        Mail::Box::Identity
47            folder_types         Mail::Box::Manager  <all standard types>
48            folderdir            Mail::Box::Manager  [ '.' ]
49            folderdirs           Mail::Box::Manager  <synonym for C<folderdir>>
50            identity                              <required>
51            inbox                                 undef
52            log                  Mail::Reporter   'WARNINGS'
53            topfolder_name                        '='
54            trace                Mail::Reporter   'WARNINGS'
55
56           . autodetect TYPE⎪ARRAY-OF-TYPES
57
58           . collection_type CLASS
59
60               Subfolders grouped together.
61
62           . default_folder_type NAME⎪CLASS
63
64           . delimiter STRING
65
66               The separator used in folder names.  This doesn't need to be
67               the same as your directory system is using.
68
69           . folder_id_type CLASS⎪OBJECT
70
71           . folder_types NEW-TYPE ⎪ ARRAY-OF-NEW-TYPES
72
73           . folderdir DIRECTORY
74
75           . folderdirs [DIRECTORIES]
76
77           . identity OBJECT
78
79               The main difference between the Mail::Box::Manager and this
80               class, is the concept of some person (or virtual person) who's
81               files are being administered by this object.  The OBJECT is an
82               User::Identity.
83
84               The smallest identity that will do: "my $id = User::Iden‐
85               tity->new('myname')"
86
87           . inbox NAME
88
89               The name of the user's inbox.
90
91           . log LEVEL
92
93           . topfolder_name STRING
94
95           . trace LEVEL
96
97       Attributes
98
99       $obj->defaultFolderType
100
101           See "Attributes" in Mail::Box::Manager
102
103       $obj->folderTypes
104
105           See "Attributes" in Mail::Box::Manager
106
107       $obj->folderdir
108
109           See "Attributes" in Mail::Box::Manager
110
111       $obj->identity
112
113           Returns a User::Identity object.
114
115       $obj->inbox([NAME])
116
117           (Set and) get the NAME of the mailbox which is considered the
118           folder for incoming mail.  In many protocols, this folder is han‐
119           dled seperately.  For instance in IMAP this is the only case-insen‐
120           sitive folder name.
121
122       $obj->registerType(TYPE, CLASS [,OPTIONS])
123
124           See "Attributes" in Mail::Box::Manager
125
126       Manage open folders
127
128       $obj->close(FOLDER, OPTIONS)
129
130           See "Manage open folders" in Mail::Box::Manager
131
132       $obj->closeAllFolders(, OPTIONS)
133
134           See "Manage open folders" in Mail::Box::Manager
135
136       $obj->isOpenFolder(FOLDER)
137
138           See "Manage open folders" in Mail::Box::Manager
139
140       $obj->open([FOLDERNAME], OPTIONS)
141
142           See "Manage open folders" in Mail::Box::Manager
143
144       $obj->openFolders
145
146           See "Manage open folders" in Mail::Box::Manager
147
148       Manage existing folders
149
150       $obj->create(NAME, OPTIONS)
151
152           Creates a new folder with the specified name.  An folder's adminis‐
153           trative structure (Mail::Box::Identity) is returned, but the folder
154           is not opened.
155
156           In the accidental case that the folder already exists, a warning
157           will be issued, and an empty list/undef returned.
158
159           The OPTIONS are passed to Mail::Box::create() of your default
160           folder type, except for the options intended for this method
161           itself.
162
163            Option       --Default
164            create_real    <true>
165            create_supers  <false>
166            deleted        <false>
167            id_options     []
168
169           . create_real BOOLEAN
170
171               When this option is false, the pysical folder will not be cre‐
172               ated, but only the administration is updated.
173
174           . create_supers BOOLEAN
175
176               When you create a folder where upper hierarchy level are miss‐
177               ing, they will be created as well.
178
179           . deleted BOOLEAN
180
181               The folder starts as deleted.
182
183           . id_options ARRAY
184
185               Values passed to the instantiated Mail::Box::Identity.  That
186               object is very picky about the initiation values it accepts.
187
188       $obj->delete(NAME)
189
190           Remove all signs from the folder on the file-system.  Messages
191           still in the folder will be removed.  This method returns a true
192           value when the folder has been removed or not found, so "false"
193           means failure.
194
195           It is also possible to delete a folder using "$folder->delete",
196           which will call this method here.  OPTIONS, which are used for some
197           other folder types, will be ignored here: the user's index contains
198           the required details.
199
200            Option   --Defined in        --Default
201            recursive  Mail::Box::Manager  <folder's default>
202
203           . recursive BOOLEAN
204
205           Example: how to delete a folder
206
207            print "no xyz (anymore)\n" if $user->delete('xyz');
208
209       $obj->folder(NAME)
210
211           Returns the folder description, a Mail::Box::Identity.
212
213       $obj->folderCollection(NAME)
214
215           Returns a pair: the folder collection (Mail::Box::Collection) and
216           the base name of NAME.
217
218       $obj->rename(OLDNAME, NEWNAME, OPTIONS)
219
220           Rename the folder with name OLDNAME to NEWNAME.  Both names are
221           full pathnames.
222
223            Option       --Default
224            create_supers  <false>
225
226           . create_supers BOOLEAN
227
228               When you rename a folder to a place where upper hierarchy lev‐
229               els are missing, they will get be defined, but with the deleted
230               flag set.
231
232       $obj->topfolder
233
234           Returns the top folder of the user's mailbox storage.
235
236       Move messages to folders
237
238       $obj->appendMessage([FOLDER⎪FOLDERNAME,] MESSAGES, OPTIONS)
239
240           See "Move messages to folders" in Mail::Box::Manager
241
242       $obj->copyMessage([FOLDER⎪FOLDERNAME,] MESSAGES, OPTIONS)
243
244           See "Move messages to folders" in Mail::Box::Manager
245
246       $obj->moveMessage([FOLDER⎪FOLDERNAME,] MESSAGES, OPTIONS)
247
248           See "Move messages to folders" in Mail::Box::Manager
249
250       Manage message threads
251
252       $obj->threads([FOLDERS], OPTIONS)
253
254           See "Manage message threads" in Mail::Box::Manager
255
256       Internals
257
258       $obj->decodeFolderURL(URL)
259
260           See "Internals" in Mail::Box::Manager
261
262       $obj->toBeThreaded(FOLDER, MESSAGES)
263
264           See "Internals" in Mail::Box::Manager
265
266       $obj->toBeUnthreaded(FOLDER, MESSAGES)
267
268           See "Internals" in Mail::Box::Manager
269
270       Error handling
271
272       $obj->AUTOLOAD
273
274           See "Error handling" in Mail::Reporter
275
276       $obj->addReport(OBJECT)
277
278           See "Error handling" in Mail::Reporter
279
280       $obj->defaultTrace([LEVEL]⎪[LOGLEVEL, TRACELEVEL]⎪[LEVEL, CALLBACK])
281
282       Mail::Box::Manage::User->defaultTrace([LEVEL]⎪[LOGLEVEL,
283       TRACELEVEL]⎪[LEVEL, CALLBACK])
284
285           See "Error handling" in Mail::Reporter
286
287       $obj->errors
288
289           See "Error handling" in Mail::Reporter
290
291       $obj->log([LEVEL [,STRINGS]])
292
293       Mail::Box::Manage::User->log([LEVEL [,STRINGS]])
294
295           See "Error handling" in Mail::Reporter
296
297       $obj->logPriority(LEVEL)
298
299       Mail::Box::Manage::User->logPriority(LEVEL)
300
301           See "Error handling" in Mail::Reporter
302
303       $obj->logSettings
304
305           See "Error handling" in Mail::Reporter
306
307       $obj->notImplemented
308
309           See "Error handling" in Mail::Reporter
310
311       $obj->report([LEVEL])
312
313           See "Error handling" in Mail::Reporter
314
315       $obj->reportAll([LEVEL])
316
317           See "Error handling" in Mail::Reporter
318
319       $obj->trace([LEVEL])
320
321           See "Error handling" in Mail::Reporter
322
323       $obj->warnings
324
325           See "Error handling" in Mail::Reporter
326
327       Cleanup
328
329       $obj->DESTROY
330
331           See "Cleanup" in Mail::Reporter
332
333       $obj->inGlobalDestruction
334
335           See "Cleanup" in Mail::Reporter
336

DETAILS

DIAGNOSTICS

339       Error: Cannot create $name: higher levels missing
340
341       Unless you set create(create_supers), all higher level folders must
342       exist before this new one can be created.
343
344       Error: Cannot rename $name to $new: higher levels missing
345
346       Unless you set create(create_supers), all higher level folders must
347       exist before this new one can be created.
348
349       Error: Folder $name is already open.
350
351       You cannot ask the manager for a folder which is already open. In some
352       older releases (before MailBox 2.049), this was permitted, but then be‐
353       haviour changed, because many nasty side-effects are to be expected.
354       For instance, an Mail::Box::update() on one folder handle would influ‐
355       ence the second, probably unexpectedly.
356
357       Error: Folder $name is not a Mail::Box; cannot add a message.
358
359       The folder where the message should be appended to is an object which
360       is not a folder type which extends Mail::Box.  Probably, it is not a
361       folder at all.
362
363       Warning: Folder does not exist, failed opening $type folder $name.
364
365       The folder does not exist and creating is not permitted (see open(cre‐
366       ate)) or did not succeed.  When you do not have sufficient access
367       rights to the folder (for instance wrong password for POP3), this warn‐
368       ing will be produced as well.
369
370       The manager tried to open a folder of the specified type.  It may help
371       to explicitly state the type of your folder with the "type" option.
372       There will probably be another warning or error message which is
373       related to this report and provides more details about its cause.  You
374       may also have a look at new(autodetect) and new(folder_types).
375
376       Warning: Folder type $type is unknown, using autodetect.
377
378       The specified folder type (see open(type), possibly derived from the
379       folder name when specified as url) is not known to the manager.  This
380       may mean that you forgot to require the Mail::Box extension which
381       implements this folder type, but probably it is a typo.  Usually, the
382       manager is able to figure-out which type to use by itself.
383
384       Error: Illegal folder URL '$url'.
385
386       The folder name was specified as URL, but not according to the syntax.
387       See decodeFolderURL() for an description of the syntax.
388
389       Error: No foldername specified to open.
390
391       "open()" needs a folder name as first argument (before the list of
392       options), or with the "folder" option within the list.  If no name was
393       found, the MAIL environment variable is checked.  When even that does
394       not result in a usable folder, then this error is produced.  The error
395       may be caused by an accidental odd-length option list.
396
397       Error: Package $package does not implement $method.
398
399       Fatal error: the specific package (or one of its superclasses) does not
400       implement this method where it should. This message means that some
401       other related classes do implement this method however the class at
402       hand does not.  Probably you should investigate this and probably
403       inform the author of the package.
404
405       Error: Unable to remove folder $dir
406
407       Error: Use appendMessage() to add messages which are not in a folder.
408
409       You do not need to copy this message into the folder, because you do
410       not share the message between folders.
411
412       Warning: Use moveMessage() or copyMessage() to move between open fold‐
413       ers.
414
415       The message is already part of a folder, and now it should be appended
416       to a different folder.  You need to decide between copy or move, which
417       both will clone the message (not the body, because they are immutable).
418
419       Warning: Will never create a folder $name without having write access.
420
421       You have set open(create), but only want to read the folder.  Create is
422       only useful for folders which have write or append access modes (see
423       Mail::Box::new(access)).
424

LICENSE

430       Copyrights 2001-2007 by Mark Overmeer.For other contributors see
431       ChangeLog.
432
433       This program is free software; you can redistribute it and/or modify it
434       under the same terms as Perl itself.  See
435       http://www.perl.com/perl/misc/Artistic.html
436
437
438
439perl v5.8.8                       2007-03-25        Mail::Box::Manage::User(3)