Mail::Box::Dir(3pm)

1Mail::Box::Dir(3)     User Contributed Perl Documentation    Mail::Box::Dir(3)
2
3
4

NAME

6       Mail::Box::Dir - handle folders with a file per message.
7

INHERITANCE

9        Mail::Box::Dir
10          is a Mail::Box
11          is a Mail::Reporter
12
13        Mail::Box::Dir is extended by
14          Mail::Box::MH
15          Mail::Box::Maildir
16

SYNOPSIS

18        # Do not instantiate this object
19

DESCRIPTION

21       This documentation describes the way directory organized mailboxes
22       work.  At the moment, this object is extended by
23
24       * Mail::Box::MH
25           MH folders, which are represented by a directory containing files
26           which are sequentially numbered.
27
28       * Mail::Box::Maildir
29           Maildir folders, which are located in a directory which has sub-
30           directories named "tmp", "new", and "cur".  Each of these directo‐
31           ries may contain files with names which are a combination of a
32           numeric timestamp and some status flags.
33
34       * Mail::Box::Netzwert
35           This folder type was especially developed for Netzwert AG, opti‐
36           mized to run on a cluster of servers with folders on NFS.  The code
37           is not publicly available (yet).
38

OVERLOADED

40       overload: ""
41
42           See "OVERLOADED" in Mail::Box
43
44       overload: @{}
45
46           See "OVERLOADED" in Mail::Box
47
48       overload: cmp
49
50           See "OVERLOADED" in Mail::Box
51

METHODS

53       Constructors
54
55       Mail::Box::Dir->new(OPTIONS)
56
57        Option           --Defined in     --Default
58        access             Mail::Box        'r'
59        body_delayed_type  Mail::Box        Mail::Message::Body::Delayed
60        body_type          Mail::Box        Mail::Message::Body::Lines
61        coerce_options     Mail::Box        []
62        create             Mail::Box        <false>
63        directory                           <derived from folder name>
64        extract            Mail::Box        10240
65        field_type         Mail::Box        undef
66        fix_headers        Mail::Box        <false>
67        folder             Mail::Box        $ENV{MAIL}
68        folderdir          Mail::Box        undef
69        head_delayed_type  Mail::Box        Mail::Message::Head::Delayed
70        head_type          Mail::Box        Mail::Message::Head::Complete
71        keep_dups          Mail::Box        <false>
72        lock_file          Mail::Box        <folder>/.lock
73        lock_timeout       Mail::Box        1 hour
74        lock_type          Mail::Box        Mail::Box::Locker::DotLock
75        lock_wait          Mail::Box        10 seconds
76        locker             Mail::Box        undef
77        log                Mail::Reporter   'WARNINGS'
78        manager            Mail::Box        undef
79        message_type       Mail::Box        Mail::Box::Message
80        multipart_type     Mail::Box        Mail::Message::Body::Multipart
81        remove_when_empty  Mail::Box        <true>
82        save_on_exit       Mail::Box        <true>
83        trace              Mail::Reporter   'WARNINGS'
84        trusted            Mail::Box        <depends on folder location>
85
86           . access MODE
87
88           . body_delayed_type CLASS
89
90           . body_type CLASS⎪CODE
91
92           . coerce_options ARRAY
93
94           . create BOOLEAN
95
96           . directory DIRECTORY
97
98               For rare folder types, the directory name may differ from the
99               folder name.
100
101           . extract INTEGER ⎪ CODE ⎪ METHOD ⎪ 'LAZY'⎪'ALWAYS'
102
103           . field_type CLASS
104
105           . fix_headers BOOLEAN
106
107           . folder FOLDERNAME
108
109           . folderdir DIRECTORY
110
111           . head_delayed_type CLASS
112
113           . head_type CLASS
114
115           . keep_dups BOOLEAN
116
117           . lock_file FILENAME
118
119           . lock_timeout SECONDS
120
121           . lock_type CLASS⎪STRING⎪ARRAY
122
123           . lock_wait SECONDS
124
125           . locker OBJECT
126
127           . log LEVEL
128
129           . manager MANAGER
130
131           . message_type CLASS
132
133           . multipart_type CLASS
134
135           . remove_when_empty BOOLEAN
136
137           . save_on_exit BOOLEAN
138
139           . trace LEVEL
140
141           . trusted BOOLEAN
142
143       The folder
144
145       $obj->addMessage(MESSAGE, OPTIONS)
146
147           See "The folder" in Mail::Box
148
149       $obj->addMessages(MESSAGE [, MESSAGE, ...])
150
151           See "The folder" in Mail::Box
152
153       Mail::Box::Dir->appendMessages(OPTIONS)
154
155           See "The folder" in Mail::Box
156
157       $obj->close(OPTIONS)
158
159           See "The folder" in Mail::Box
160
161       $obj->copyTo(FOLDER, OPTIONS)
162
163           See "The folder" in Mail::Box
164
165       $obj->delete(OPTIONS)
166
167           See "The folder" in Mail::Box
168
169       $obj->directory
170
171           Returns the directory related to this folder.
172
173           Example:
174
175            print $folder->directory;
176
177       $obj->folderdir([DIRECTORY])
178
179           See "The folder" in Mail::Box
180
181       $obj->name
182
183           See "The folder" in Mail::Box
184
185       $obj->organization
186
187           See "The folder" in Mail::Box
188
189       $obj->size
190
191           See "The folder" in Mail::Box
192
193       $obj->type
194
195           See "The folder" in Mail::Box
196
197       $obj->update(OPTIONS)
198
199           See "The folder" in Mail::Box
200
201       $obj->url
202
203           See "The folder" in Mail::Box
204
205       Folder flags
206
207       $obj->access
208
209           See "Folder flags" in Mail::Box
210
211       $obj->isModified
212
213           See "Folder flags" in Mail::Box
214
215       $obj->modified([BOOLEAN])
216
217           See "Folder flags" in Mail::Box
218
219       $obj->writable
220
221           See "Folder flags" in Mail::Box
222
223       The messages
224
225       $obj->current([NUMBER⎪MESSAGE⎪MESSAGE-ID])
226
227           See "The messages" in Mail::Box
228
229       $obj->find(MESSAGE-ID)
230
231           See "The messages" in Mail::Box
232
233       $obj->findFirstLabeled(LABEL, [BOOLEAN, [ARRAY-OF-MSGS]])
234
235           See "The messages" in Mail::Box
236
237       $obj->message(INDEX [,MESSAGE])
238
239           See "The messages" in Mail::Box
240
241       $obj->messageId(MESSAGE-ID [,MESSAGE])
242
243           See "The messages" in Mail::Box
244
245       $obj->messageIds
246
247           See "The messages" in Mail::Box
248
249       $obj->messages(['ALL',RANGE,'ACTIVE','DELETED',LABEL,!LABEL,FILTER])
250
251           See "The messages" in Mail::Box
252
253       $obj->nrMessages(OPTIONS)
254
255           See "The messages" in Mail::Box
256
257       $obj->scanForMessages(MESSAGE, MESSAGE-IDS, TIMESPAN, WINDOW)
258
259           See "The messages" in Mail::Box
260
261       Sub-folders
262
263       $obj->listSubFolders(OPTIONS)
264
265       Mail::Box::Dir->listSubFolders(OPTIONS)
266
267           See "Sub-folders" in Mail::Box
268
269       $obj->nameOfSubFolder(SUBNAME, [PARENTNAME])
270
271       Mail::Box::Dir->nameOfSubFolder(SUBNAME, [PARENTNAME])
272
273           See "Sub-folders" in Mail::Box
274
275       $obj->openRelatedFolder(OPTIONS)
276
277           See "Sub-folders" in Mail::Box
278
279       $obj->openSubFolder(SUBNAME, OPTIONS)
280
281           See "Sub-folders" in Mail::Box
282
283       $obj->topFolderWithMessages
284
285       Mail::Box::Dir->topFolderWithMessages
286
287           See "Sub-folders" in Mail::Box
288
289       Internals
290
291       $obj->coerce(MESSAGE, OPTIONS)
292
293           See "Internals" in Mail::Box
294
295       $obj->create(FOLDERNAME, OPTIONS)
296
297       Mail::Box::Dir->create(FOLDERNAME, OPTIONS)
298
299           See "Internals" in Mail::Box
300
301       $obj->determineBodyType(MESSAGE, HEAD)
302
303           See "Internals" in Mail::Box
304
305       $obj->folderToDirectory(FOLDERNAME, FOLDERDIR)
306
307           (class method)  Translate a foldername into a filename, with use of
308           the FOLDERDIR to replace a leading "=".
309
310       Mail::Box::Dir->foundIn([FOLDERNAME], OPTIONS)
311
312           See "Internals" in Mail::Box
313
314       $obj->lineSeparator([STRING⎪'CR'⎪'LF'⎪'CRLF'])
315
316           See "Internals" in Mail::Box
317
318       $obj->locker
319
320           See "Internals" in Mail::Box
321
322       $obj->read(OPTIONS)
323
324           See "Internals" in Mail::Box
325
326       $obj->readMessageFilenames(DIRECTORY)
327
328           Returns a list of all filenames which are found in this folder
329           directory and represent a message.  The filenames are returned as
330           relative path.
331
332       $obj->readMessages(OPTIONS)
333
334           See "Internals" in Mail::Box
335
336       $obj->storeMessage(MESSAGE)
337
338           See "Internals" in Mail::Box
339
340       $obj->toBeThreaded(MESSAGES)
341
342           See "Internals" in Mail::Box
343
344       $obj->toBeUnthreaded(MESSAGES)
345
346           See "Internals" in Mail::Box
347
348       $obj->updateMessages(OPTIONS)
349
350           See "Internals" in Mail::Box
351
352       $obj->write(OPTIONS)
353
354           See "Internals" in Mail::Box
355
356       $obj->writeMessages(OPTIONS)
357
358           See "Internals" in Mail::Box
359
360       Other methods
361
362       $obj->timespan2seconds(TIME)
363
364       Mail::Box::Dir->timespan2seconds(TIME)
365
366           See "Other methods" in Mail::Box
367
368       Error handling
369
370       $obj->AUTOLOAD
371
372           See "Error handling" in Mail::Reporter
373
374       $obj->addReport(OBJECT)
375
376           See "Error handling" in Mail::Reporter
377
378       $obj->defaultTrace([LEVEL]⎪[LOGLEVEL, TRACELEVEL]⎪[LEVEL, CALLBACK])
379
380       Mail::Box::Dir->defaultTrace([LEVEL]⎪[LOGLEVEL, TRACELEVEL]⎪[LEVEL,
381       CALLBACK])
382
383           See "Error handling" in Mail::Reporter
384
385       $obj->errors
386
387           See "Error handling" in Mail::Reporter
388
389       $obj->log([LEVEL [,STRINGS]])
390
391       Mail::Box::Dir->log([LEVEL [,STRINGS]])
392
393           See "Error handling" in Mail::Reporter
394
395       $obj->logPriority(LEVEL)
396
397       Mail::Box::Dir->logPriority(LEVEL)
398
399           See "Error handling" in Mail::Reporter
400
401       $obj->logSettings
402
403           See "Error handling" in Mail::Reporter
404
405       $obj->notImplemented
406
407           See "Error handling" in Mail::Reporter
408
409       $obj->report([LEVEL])
410
411           See "Error handling" in Mail::Reporter
412
413       $obj->reportAll([LEVEL])
414
415           See "Error handling" in Mail::Reporter
416
417       $obj->trace([LEVEL])
418
419           See "Error handling" in Mail::Reporter
420
421       $obj->warnings
422
423           See "Error handling" in Mail::Reporter
424
425       Cleanup
426
427       $obj->DESTROY
428
429           See "Cleanup" in Mail::Box
430
431       $obj->inGlobalDestruction
432
433           See "Cleanup" in Mail::Reporter
434

DETAILS

DIAGNOSTICS

437       Warning: Changes not written to read-only folder $self.
438
439       You have opened the folder read-only --which is the default set by
440       new(access)--, made modifications, and now want to close it.  Set
441       close(force) if you want to overrule the access mode, or close the
442       folder with close(write) set to "NEVER".
443
444       Error: Copying failed for one message.
445
446       For some reason, for instance disc full, removed by external process,
447       or read-protection, it is impossible to copy one of the messages.
448       Copying will proceed for the other messages.
449
450       Error: Destination folder $name is not writable.
451
452       The folder where the messages are copied to is not opened with write
453       access (see new(access)).  This has no relation with write permission
454       to the folder which is controled by your operating system.
455
456       Warning: Different messages with id $msgid
457
458       The message id is discovered more than once within the same folder, but
459       the content of the message seems to be different.  This should not be
460       possible: each message must be unique.
461
462       Error: Folder $name is opened read-only
463
464       You can not write to this folder unless you have opened the folder to
465       write or append with new(access), or the "force" option is set true.
466
467       Error: Folder $name not deleted: not writable.
468
469       The folder must be opened with write access via new(access), otherwise
470       removing it will be refused.  So, you may have write-access according
471       to the operating system, but that will not automatically mean that this
472       "delete" method permits you to.  The reverse remark is valid as well.
473
474       Warning: Folder directory $directory is write-protected.
475
476       The folder directory does already exist and is write protected, which
477       may interfere with the requested write access.  Change new(access) or
478       the permissions on the directory.
479
480       Error: Invalid timespan '$timespan' specified.
481
482       The string does not follow the strict rules of the time span syntax
483       which is permitted as parameter.
484
485       Warning: Message-id '$msgid' does not contain a domain.
486
487       According to the RFCs, message-ids need to contain a unique random
488       part, then an "@", and then a domain name.  This is made to avoid the
489       creation of two messages with the same id.  The warning emerges when
490       the "@" is missing from the string.
491
492       Warning: No directory $name for folder of $class
493
494       Error: Package $package does not implement $method.
495
496       Fatal error: the specific package (or one of its superclasses) does not
497       implement this method where it should. This message means that some
498       other related classes do implement this method however the class at
499       hand does not.  Probably you should investigate this and probably
500       inform the author of the package.
501
502       Error: Unable to create subfolder $name of $folder.
503
504       The copy includes the subfolders, but for some reason it was not possi‐
505       ble to copy one of these.  Copying will proceed for all other sub-fold‐
506       ers.
507
508       Error: Writing folder $name failed
509
510       For some reason (you probably got more error messages about this prob‐
511       lem) it is impossible to write the folder, although you should because
512       there were changes made.
513

LICENSE

519       Copyrights 2001-2007 by Mark Overmeer.For other contributors see
520       ChangeLog.
521
522       This program is free software; you can redistribute it and/or modify it
523       under the same terms as Perl itself.  See
524       http://www.perl.com/perl/misc/Artistic.html
525
526
527
528perl v5.8.8                       2007-03-25                 Mail::Box::Dir(3)