1Mail::Box::Dir(3) User Contributed Perl Documentation Mail::Box::Dir(3)
2
6 Mail::Box::Dir - handle folders with a file per message.
7
9 Mail::Box::Dir
10 is a Mail::Box
11 is a Mail::Reporter
12 Mail::Box::Dir is extended by
14 Mail::Box::MH
15 Mail::Box::Maildir
16
18 # Do not instantiate this object
19
21 This documentation describes the way directory organized mailboxes
22 work. At the moment, this object is extended by
23 · Mail::Box::MH
25 MH folders, which are represented by a directory containing files
27 which are sequentially numbered.
28 · Mail::Box::Maildir
30 Maildir folders, which are located in a directory which has sub-
32 directories named "tmp", "new", and "cur". Each of these
33 directories may contain files with names which are a combination of
34 a numeric timestamp and some status flags.
35 · Mail::Box::Netzwert
37 This folder type was especially developed for Netzwert AG,
39 optimized to run on a cluster of servers with folders on NFS. The
40 code is not publicly available (yet).
41
43 overload: ""
44 See "OVERLOADED" in Mail::Box
45 overload: @{}
47 See "OVERLOADED" in Mail::Box
48 overload: cmp
50 See "OVERLOADED" in Mail::Box
51
53 Constructors
54 Mail::Box::Dir->new(OPTIONS)
55 -Option --Defined in --Default
56 access Mail::Box 'r'
57 body_delayed_type Mail::Box Mail::Message::Body::Delayed
58 body_type Mail::Box Mail::Message::Body::Lines
59 coerce_options Mail::Box []
60 create Mail::Box <false>
61 directory <derived from folder name>
62 extract Mail::Box 10240
63 field_type Mail::Box undef
64 fix_headers Mail::Box <false>
65 folder Mail::Box $ENV{MAIL}
66 folderdir Mail::Box undef
67 head_delayed_type Mail::Box Mail::Message::Head::Delayed
68 head_type Mail::Box Mail::Message::Head::Complete
69 keep_dups Mail::Box <false>
70 lock_file Mail::Box <folder>/.lock
71 lock_timeout Mail::Box 1 hour
72 lock_type Mail::Box Mail::Box::Locker::DotLock
73 lock_wait Mail::Box 10 seconds
74 locker Mail::Box undef
75 log Mail::Reporter 'WARNINGS'
76 manager Mail::Box undef
77 message_type Mail::Box Mail::Box::Message
78 multipart_type Mail::Box Mail::Message::Body::Multipart
79 remove_when_empty Mail::Box <true>
80 save_on_exit Mail::Box <true>
81 trace Mail::Reporter 'WARNINGS'
82 trusted Mail::Box <depends on folder location>
83 access => MODE
85 body_delayed_type => CLASS
86 body_type => CLASS|CODE
87 coerce_options => ARRAY
88 create => BOOLEAN
89 directory => DIRECTORY
90 For rare folder types, the directory name may differ from the
91 folder name.
92 extract => INTEGER | CODE | METHOD | 'LAZY'|'ALWAYS'
94 field_type => CLASS
95 fix_headers => BOOLEAN
96 folder => FOLDERNAME
97 folderdir => DIRECTORY
98 head_delayed_type => CLASS
99 head_type => CLASS
100 keep_dups => BOOLEAN
101 lock_file => FILENAME
102 lock_timeout => SECONDS
103 lock_type => CLASS|STRING|ARRAY
104 lock_wait => SECONDS
105 locker => OBJECT
106 log => LEVEL
107 manager => MANAGER
108 message_type => CLASS
109 multipart_type => CLASS
110 remove_when_empty => BOOLEAN
111 save_on_exit => BOOLEAN
112 trace => LEVEL
113 trusted => BOOLEAN
114 The folder
116 $obj->addMessage(MESSAGE, OPTIONS)
117 See "The folder" in Mail::Box
118 $obj->addMessages(MESSAGE [, MESSAGE, ...])
120 See "The folder" in Mail::Box
121 Mail::Box::Dir->appendMessages(OPTIONS)
123 See "The folder" in Mail::Box
124 $obj->close(OPTIONS)
126 See "The folder" in Mail::Box
127 $obj->copyTo(FOLDER, OPTIONS)
129 See "The folder" in Mail::Box
130 $obj->delete(OPTIONS)
132 See "The folder" in Mail::Box
133 $obj->directory
135 Returns the directory related to this folder.
136 example:
138 print $folder->directory;
140 $obj->folderdir([DIRECTORY])
142 See "The folder" in Mail::Box
143 $obj->name
145 See "The folder" in Mail::Box
146 $obj->organization
148 See "The folder" in Mail::Box
149 $obj->size
151 See "The folder" in Mail::Box
152 $obj->type
154 See "The folder" in Mail::Box
155 $obj->update(OPTIONS)
157 See "The folder" in Mail::Box
158 $obj->url
160 See "The folder" in Mail::Box
161 Folder flags
163 $obj->access
164 See "Folder flags" in Mail::Box
165 $obj->isModified
167 See "Folder flags" in Mail::Box
168 $obj->modified([BOOLEAN])
170 See "Folder flags" in Mail::Box
171 $obj->writable
173 See "Folder flags" in Mail::Box
174 The messages
176 $obj->current([NUMBER|MESSAGE|MESSAGE-ID])
177 See "The messages" in Mail::Box
178 $obj->find(MESSAGE-ID)
180 See "The messages" in Mail::Box
181 $obj->findFirstLabeled(LABEL, [BOOLEAN, [ARRAY-OF-MSGS]])
183 See "The messages" in Mail::Box
184 $obj->message(INDEX [,MESSAGE])
186 See "The messages" in Mail::Box
187 $obj->messageId(MESSAGE-ID [,MESSAGE])
189 See "The messages" in Mail::Box
190 $obj->messageIds
192 See "The messages" in Mail::Box
193 $obj->messages(['ALL',RANGE,'ACTIVE','DELETED',LABEL,!LABEL,FILTER])
195 See "The messages" in Mail::Box
196 $obj->nrMessages(OPTIONS)
198 See "The messages" in Mail::Box
199 $obj->scanForMessages(MESSAGE, MESSAGE-IDS, TIMESPAN, WINDOW)
201 See "The messages" in Mail::Box
202 Sub-folders
204 $obj->listSubFolders(OPTIONS)
205 Mail::Box::Dir->listSubFolders(OPTIONS)
206 See "Sub-folders" in Mail::Box
208 $obj->nameOfSubFolder(SUBNAME, [PARENTNAME])
210 Mail::Box::Dir->nameOfSubFolder(SUBNAME, [PARENTNAME])
211 See "Sub-folders" in Mail::Box
213 $obj->openRelatedFolder(OPTIONS)
215 See "Sub-folders" in Mail::Box
216 $obj->openSubFolder(SUBNAME, OPTIONS)
218 See "Sub-folders" in Mail::Box
219 $obj->topFolderWithMessages
221 Mail::Box::Dir->topFolderWithMessages
222 See "Sub-folders" in Mail::Box
224 Internals
226 $obj->coerce(MESSAGE, OPTIONS)
227 See "Internals" in Mail::Box
228 $obj->create(FOLDERNAME, OPTIONS)
230 Mail::Box::Dir->create(FOLDERNAME, OPTIONS)
231 See "Internals" in Mail::Box
233 $obj->determineBodyType(MESSAGE, HEAD)
235 See "Internals" in Mail::Box
236 $obj->folderToDirectory(FOLDERNAME, FOLDERDIR)
238 (class method) Translate a foldername into a filename, with use of
239 the FOLDERDIR to replace a leading "=".
240 Mail::Box::Dir->foundIn([FOLDERNAME], OPTIONS)
242 See "Internals" in Mail::Box
243 $obj->lineSeparator([STRING|'CR'|'LF'|'CRLF'])
245 See "Internals" in Mail::Box
246 $obj->locker
248 See "Internals" in Mail::Box
249 $obj->read(OPTIONS)
251 See "Internals" in Mail::Box
252 $obj->readMessageFilenames(DIRECTORY)
254 Returns a list of all filenames which are found in this folder
255 directory and represent a message. The filenames are returned as
256 relative path.
257 $obj->readMessages(OPTIONS)
259 See "Internals" in Mail::Box
260 $obj->storeMessage(MESSAGE)
262 See "Internals" in Mail::Box
263 $obj->toBeThreaded(MESSAGES)
265 See "Internals" in Mail::Box
266 $obj->toBeUnthreaded(MESSAGES)
268 See "Internals" in Mail::Box
269 $obj->updateMessages(OPTIONS)
271 See "Internals" in Mail::Box
272 $obj->write(OPTIONS)
274 See "Internals" in Mail::Box
275 $obj->writeMessages(OPTIONS)
277 See "Internals" in Mail::Box
278 Other methods
280 $obj->timespan2seconds(TIME)
281 Mail::Box::Dir->timespan2seconds(TIME)
282 See "Other methods" in Mail::Box
284 Error handling
286 $obj->AUTOLOAD
287 See "Error handling" in Mail::Reporter
288 $obj->addReport(OBJECT)
290 See "Error handling" in Mail::Reporter
291 $obj->defaultTrace([LEVEL]|[LOGLEVEL, TRACELEVEL]|[LEVEL, CALLBACK])
293 Mail::Box::Dir->defaultTrace([LEVEL]|[LOGLEVEL, TRACELEVEL]|[LEVEL,
294 CALLBACK])
295 See "Error handling" in Mail::Reporter
297 $obj->errors
299 See "Error handling" in Mail::Reporter
300 $obj->log([LEVEL [,STRINGS]])
302 Mail::Box::Dir->log([LEVEL [,STRINGS]])
303 See "Error handling" in Mail::Reporter
305 $obj->logPriority(LEVEL)
307 Mail::Box::Dir->logPriority(LEVEL)
308 See "Error handling" in Mail::Reporter
310 $obj->logSettings
312 See "Error handling" in Mail::Reporter
313 $obj->notImplemented
315 See "Error handling" in Mail::Reporter
316 $obj->report([LEVEL])
318 See "Error handling" in Mail::Reporter
319 $obj->reportAll([LEVEL])
321 See "Error handling" in Mail::Reporter
322 $obj->trace([LEVEL])
324 See "Error handling" in Mail::Reporter
325 $obj->warnings
327 See "Error handling" in Mail::Reporter
328 Cleanup
330 $obj->DESTROY
331 See "Cleanup" in Mail::Box
332 $obj->inGlobalDestruction
334 See "Cleanup" in Mail::Reporter
335
337 Warning: Changes not written to read-only folder $self.
338 You have opened the folder read-only --which is the default set by
339 new(access)--, made modifications, and now want to close it. Set
340 close(force) if you want to overrule the access mode, or close the
341 folder with close(write) set to "NEVER".
342 Error: Copying failed for one message.
344 For some reason, for instance disc full, removed by external
345 process, or read-protection, it is impossible to copy one of the
346 messages. Copying will proceed for the other messages.
347 Error: Destination folder $name is not writable.
349 The folder where the messages are copied to is not opened with
350 write access (see new(access)). This has no relation with write
351 permission to the folder which is controled by your operating
352 system.
353 Warning: Different messages with id $msgid
355 The message id is discovered more than once within the same folder,
356 but the content of the message seems to be different. This should
357 not be possible: each message must be unique.
358 Error: Folder $name is opened read-only
360 You can not write to this folder unless you have opened the folder
361 to write or append with new(access), or the "force" option is set
362 true.
363 Error: Folder $name not deleted: not writable.
365 The folder must be opened with write access via new(access),
366 otherwise removing it will be refused. So, you may have write-
367 access according to the operating system, but that will not
368 automatically mean that this "delete" method permits you to. The
369 reverse remark is valid as well.
370 Warning: Folder directory $directory is write-protected.
372 The folder directory does already exist and is write protected,
373 which may interfere with the requested write access. Change
374 new(access) or the permissions on the directory.
375 Error: Invalid timespan '$timespan' specified.
377 The string does not follow the strict rules of the time span syntax
378 which is permitted as parameter.
379 Warning: Message-id '$msgid' does not contain a domain.
381 According to the RFCs, message-ids need to contain a unique random
382 part, then an "@", and then a domain name. This is made to avoid
383 the creation of two messages with the same id. The warning emerges
384 when the "@" is missing from the string.
385 Warning: No directory $name for folder of $class
387 Error: Package $package does not implement $method.
388 Fatal error: the specific package (or one of its superclasses) does
389 not implement this method where it should. This message means that
390 some other related classes do implement this method however the
391 class at hand does not. Probably you should investigate this and
392 probably inform the author of the package.
393 Error: Unable to create subfolder $name of $folder.
395 The copy includes the subfolders, but for some reason it was not
396 possible to copy one of these. Copying will proceed for all other
397 sub-folders.
398 Error: Writing folder $name failed
400 For some reason (you probably got more error messages about this
401 problem) it is impossible to write the folder, although you should
402 because there were changes made.
403
405 This module is part of Mail-Box distribution version 2.097, built on
406 January 26, 2011. Website: http://perl.overmeer.net/mailbox/
407
409 Copyrights 2001-2011 by Mark Overmeer. For other contributors see
410 ChangeLog.
411 This program is free software; you can redistribute it and/or modify it
413 under the same terms as Perl itself. See
414 http://www.perl.com/perl/misc/Artistic.html
415perl v5.12.3 2011-01-26 Mail::Box::Dir(3)