1Mail::Box::Manage::UserU(s3e)r Contributed Perl DocumentaMtaiioln::Box::Manage::User(3)
2
3
4
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
13 Mail::Box::Manage::User is extended by
14 Mail::Server::IMAP4::User
15
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
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
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
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
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
375 This module is part of Mail-Box distribution version 3.006, built on
376 February 15, 2019. Website: http://perl.overmeer.net/CPAN/
377
379 Copyrights 2001-2019 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.28.1 2019-02-15 Mail::Box::Manage::User(3)