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
14 use Mail::Box::Manage::User;
15 use User::Identity;
16 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 my $inbox = $user->open($user->inbox);
25 my $top = $user->topfolder;
26
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
34 Constructors
35 Mail::Box::Manage::User->new(ARGS)
36 Use new(default_folder_type) to explicitly state which kind of
37 folders you use.
38 -Option --Defined in --Default
40 autodetect Mail::Box::Manager undef
41 collection_type Mail::Box::Collection
42 default_folder_type Mail::Box::Manager 'mbox'
43 delimiter "/"
44 folder_id_type Mail::Box::Identity
45 folder_types Mail::Box::Manager <all standard types>
46 folderdir Mail::Box::Manager [ '.' ]
47 folderdirs Mail::Box::Manager <synonym for C<folderdir>>
48 identity <required>
49 inbox undef
50 log Mail::Reporter 'WARNINGS'
51 topfolder_name '='
52 trace Mail::Reporter 'WARNINGS'
53 autodetect => TYPE|ARRAY-OF-TYPES
55 collection_type => CLASS
56 Subfolders grouped together.
57 default_folder_type => NAME|CLASS
59 delimiter => STRING
60 The separator used in folder names. This doesn't need to be the
61 same as your directory system is using.
62 folder_id_type => CLASS|OBJECT
64 folder_types => NEW-TYPE | ARRAY-OF-NEW-TYPES
65 folderdir => DIRECTORY
66 folderdirs => [DIRECTORIES]
67 identity => OBJECT
68 The main difference between the Mail::Box::Manager and this
69 class, is the concept of some person (or virtual person) who's
70 files are being administered by this object. The OBJECT is an
71 User::Identity.
72 The smallest identity that will do: "my $id =
74 User::Identity->new('myname')"
75 inbox => NAME
77 The name of the user's inbox.
78 log => LEVEL
80 topfolder_name => STRING
81 trace => LEVEL
82 Attributes
84 $obj->defaultFolderType
85 See "Attributes" in Mail::Box::Manager
86 $obj->folderTypes
88 See "Attributes" in Mail::Box::Manager
89 $obj->folderdir
91 See "Attributes" in Mail::Box::Manager
92 $obj->identity
94 Returns a User::Identity object.
95 $obj->inbox([NAME])
97 (Set and) get the NAME of the mailbox which is considered the
98 folder for incoming mail. In many protocols, this folder is
99 handled separately. For instance in IMAP this is the only case-
100 insensitive folder name.
101 $obj->registerType(TYPE, CLASS [,OPTIONS])
103 See "Attributes" in Mail::Box::Manager
104 Manage open folders
106 $obj->close(FOLDER, OPTIONS)
107 See "Manage open folders" in Mail::Box::Manager
108 $obj->closeAllFolders(, OPTIONS)
110 See "Manage open folders" in Mail::Box::Manager
111 $obj->isOpenFolder(FOLDER)
113 See "Manage open folders" in Mail::Box::Manager
114 $obj->open([FOLDERNAME], OPTIONS)
116 See "Manage open folders" in Mail::Box::Manager
117 $obj->openFolders
119 See "Manage open folders" in Mail::Box::Manager
120 Manage existing folders
122 $obj->create(NAME, OPTIONS)
123 Creates a new folder with the specified name. An folder's
124 administrative structure (Mail::Box::Identity) is returned, but the
125 folder is not opened.
126 In the accidental case that the folder already exists, a warning
128 will be issued, and an empty list/undef returned.
129 The OPTIONS are passed to Mail::Box::create() of your default
131 folder type, except for the options intended for this method
132 itself.
133 -Option --Default
135 create_real <true>
136 create_supers <false>
137 deleted <false>
138 id_options []
139 create_real => BOOLEAN
141 When this option is false, the pysical folder will not be
142 created, but only the administration is updated.
143 create_supers => BOOLEAN
145 When you create a folder where upper hierarchy level are missing,
146 they will be created as well.
147 deleted => BOOLEAN
149 The folder starts as deleted.
150 id_options => ARRAY
152 Values passed to the instantiated Mail::Box::Identity. That
153 object is very picky about the initiation values it accepts.
154 $obj->delete(NAME)
156 Remove all signs from the folder on the file-system. Messages
157 still in the folder will be removed. This method returns a true
158 value when the folder has been removed or not found, so "false"
159 means failure.
160 It is also possible to delete a folder using "$folder->delete",
162 which will call this method here. OPTIONS, which are used for some
163 other folder types, will be ignored here: the user's index contains
164 the required details.
165 -Option --Defined in --Default
167 recursive Mail::Box::Manager <folder's default>
168 recursive => BOOLEAN
170 example: how to delete a folder
172 print "no xyz (anymore)\n" if $user->delete('xyz');
174 $obj->folder(NAME)
176 Returns the folder description, a Mail::Box::Identity.
177 $obj->folderCollection(NAME)
179 Returns a pair: the folder collection (Mail::Box::Collection) and
180 the base name of NAME.
181 $obj->rename(OLDNAME, NEWNAME, OPTIONS)
183 Rename the folder with name OLDNAME to NEWNAME. Both names are
184 full pathnames.
185 -Option --Default
187 create_supers <false>
188 create_supers => BOOLEAN
190 When you rename a folder to a place where upper hierarchy levels
191 are missing, they will get be defined, but with the deleted flag
192 set.
193 $obj->topfolder
195 Returns the top folder of the user's mailbox storage.
196 Move messages to folders
198 $obj->appendMessage([FOLDER|FOLDERNAME,] MESSAGES, OPTIONS)
199 See "Move messages to folders" in Mail::Box::Manager
200 $obj->copyMessage([FOLDER|FOLDERNAME,] MESSAGES, OPTIONS)
202 See "Move messages to folders" in Mail::Box::Manager
203 $obj->moveMessage([FOLDER|FOLDERNAME,] MESSAGES, OPTIONS)
205 See "Move messages to folders" in Mail::Box::Manager
206 Manage message threads
208 $obj->threads([FOLDERS], OPTIONS)
209 See "Manage message threads" in Mail::Box::Manager
210 Internals
212 $obj->decodeFolderURL(URL)
213 See "Internals" in Mail::Box::Manager
214 $obj->toBeThreaded(FOLDER, MESSAGES)
216 See "Internals" in Mail::Box::Manager
217 $obj->toBeUnthreaded(FOLDER, MESSAGES)
219 See "Internals" in Mail::Box::Manager
220 Error handling
222 $obj->AUTOLOAD
223 See "Error handling" in Mail::Reporter
224 $obj->addReport(OBJECT)
226 See "Error handling" in Mail::Reporter
227 $obj->defaultTrace([LEVEL]|[LOGLEVEL, TRACELEVEL]|[LEVEL, CALLBACK])
229 Mail::Box::Manage::User->defaultTrace([LEVEL]|[LOGLEVEL,
230 TRACELEVEL]|[LEVEL, CALLBACK])
231 See "Error handling" in Mail::Reporter
233 $obj->errors
235 See "Error handling" in Mail::Reporter
236 $obj->log([LEVEL [,STRINGS]])
238 Mail::Box::Manage::User->log([LEVEL [,STRINGS]])
239 See "Error handling" in Mail::Reporter
241 $obj->logPriority(LEVEL)
243 Mail::Box::Manage::User->logPriority(LEVEL)
244 See "Error handling" in Mail::Reporter
246 $obj->logSettings
248 See "Error handling" in Mail::Reporter
249 $obj->notImplemented
251 See "Error handling" in Mail::Reporter
252 $obj->report([LEVEL])
254 See "Error handling" in Mail::Reporter
255 $obj->reportAll([LEVEL])
257 See "Error handling" in Mail::Reporter
258 $obj->trace([LEVEL])
260 See "Error handling" in Mail::Reporter
261 $obj->warnings
263 See "Error handling" in Mail::Reporter
264 Cleanup
266 $obj->DESTROY
267 See "Cleanup" in Mail::Reporter
268 $obj->inGlobalDestruction
270 See "Cleanup" in Mail::Reporter
271
273 Error: Cannot create $name: higher levels missing
274 Unless you set create(create_supers), all higher level folders must
275 exist before this new one can be created.
276 Error: Cannot rename $name to $new: higher levels missing
278 Unless you set create(create_supers), all higher level folders must
279 exist before this new one can be created.
280 Error: Folder $name is already open.
282 You cannot ask the manager for a folder which is already open. In
283 some older releases (before MailBox 2.049), this was permitted, but
284 then behaviour changed, because many nasty side-effects are to be
285 expected. For instance, an Mail::Box::update() on one folder
286 handle would influence the second, probably unexpectedly.
287 Error: Folder $name is not a Mail::Box; cannot add a message.
289 The folder where the message should be appended to is an object
290 which is not a folder type which extends Mail::Box. Probably, it
291 is not a folder at all.
292 Warning: Folder does not exist, failed opening $type folder $name.
294 The folder does not exist and creating is not permitted (see
295 open(create)) or did not succeed. When you do not have sufficient
296 access rights to the folder (for instance wrong password for POP3),
297 this warning will be produced as well.
298 The manager tried to open a folder of the specified type. It may
300 help to explicitly state the type of your folder with the "type"
301 option. There will probably be another warning or error message
302 which is related to this report and provides more details about its
303 cause. You may also have a look at new(autodetect) and
304 new(folder_types).
305 Warning: Folder type $type is unknown, using autodetect.
307 The specified folder type (see open(type), possibly derived from
308 the folder name when specified as url) is not known to the manager.
309 This may mean that you forgot to require the Mail::Box extension
310 which implements this folder type, but probably it is a typo.
311 Usually, the manager is able to figure-out which type to use by
312 itself.
313 Error: Illegal folder URL '$url'.
315 The folder name was specified as URL, but not according to the
316 syntax. See decodeFolderURL() for an description of the syntax.
317 Error: No foldername specified to open.
319 "open()" needs a folder name as first argument (before the list of
320 options), or with the "folder" option within the list. If no name
321 was found, the MAIL environment variable is checked. When even
322 that does not result in a usable folder, then this error is
323 produced. The error may be caused by an accidental odd-length
324 option list.
325 Error: Package $package does not implement $method.
327 Fatal error: the specific package (or one of its superclasses) does
328 not implement this method where it should. This message means that
329 some other related classes do implement this method however the
330 class at hand does not. Probably you should investigate this and
331 probably inform the author of the package.
332 Error: Unable to remove folder $dir
334 Error: Use appendMessage() to add messages which are not in a folder.
335 You do not need to copy this message into the folder, because you
336 do not share the message between folders.
337 Warning: Use moveMessage() or copyMessage() to move between open
339 folders.
340 The message is already part of a folder, and now it should be
341 appended to a different folder. You need to decide between copy or
342 move, which both will clone the message (not the body, because they
343 are immutable).
344 Warning: Will never create a folder $name without having write access.
346 You have set open(create), but only want to read the folder.
347 Create is only useful for folders which have write or append access
348 modes (see Mail::Box::new(access)).
349
351 This module is part of Mail-Box distribution version 2.097, built on
352 January 26, 2011. Website: http://perl.overmeer.net/mailbox/
353
355 Copyrights 2001-2011 by Mark Overmeer. For other contributors see
356 ChangeLog.
357 This program is free software; you can redistribute it and/or modify it
359 under the same terms as Perl itself. See
360 http://www.perl.com/perl/misc/Artistic.html
361perl v5.12.3 2011-01-26 Mail::Box::Manage::User(3)