Mail::Box::Maildir::Message(3pm)

1Mail::Box::Maildir::MesUssaegre(C3o)ntributed Perl DocumMeanitla:t:iBoonx::Maildir::Message(3)
2
3
4

NAME

6       Mail::Box::Maildir::Message - one message in a Maildir folder
7

INHERITANCE

9        Mail::Box::Maildir::Message
10          is a Mail::Box::Dir::Message
11          is a Mail::Box::Message
12          is a Mail::Message
13          is a Mail::Reporter
14

SYNOPSIS

16        my $folder = new Mail::Box::Maildir ...
17        my $message = $folder->message(10);
18

DESCRIPTION

20       A "Mail::Box::Maildir::Message" represents one message in an
21       Mail::Box::Maildir folder. Each message is stored in a separate file.
22

METHODS

24       Constructors
25
26       $obj->clone(OPTIONS)
27
28           See "Constructors" in Mail::Message
29
30       Mail::Box::Maildir::Message->new(OPTIONS)
31
32           See "METHODS" in Mail::Box::Dir::Message
33
34       Constructing a message
35
36       $obj->bounce([RG-OBJECT⎪OPTIONS])
37
38           See "Constructing a message" in Mail::Message::Construct::Bounce
39
40       Mail::Box::Maildir::Message->build([MESSAGE⎪PART⎪BODY], CONTENT)
41
42           See "Constructing a message" in Mail::Message::Construct::Build
43
44       Mail::Box::Maildir::Message->buildFromBody(BODY, [HEAD], HEADERS)
45
46           See "Constructing a message" in Mail::Message::Construct::Build
47
48       $obj->forward(OPTIONS)
49
50           See "Constructing a message" in Mail::Message::Construct::Forward
51
52       $obj->forwardAttach(OPTIONS)
53
54           See "Constructing a message" in Mail::Message::Construct::Forward
55
56       $obj->forwardEncapsulate(OPTIONS)
57
58           See "Constructing a message" in Mail::Message::Construct::Forward
59
60       $obj->forwardInline(OPTIONS)
61
62           See "Constructing a message" in Mail::Message::Construct::Forward
63
64       $obj->forwardNo(OPTIONS)
65
66           See "Constructing a message" in Mail::Message::Construct::Forward
67
68       $obj->forwardPostlude
69
70           See "Constructing a message" in Mail::Message::Construct::Forward
71
72       $obj->forwardPrelude
73
74           See "Constructing a message" in Mail::Message::Construct::Forward
75
76       $obj->forwardSubject(STRING)
77
78           See "Constructing a message" in Mail::Message::Construct::Forward
79
80       Mail::Box::Maildir::Message->read(FILEHAN‐
81       DLE⎪SCALAR⎪REF-SCALAR⎪ARRAY-OF-LINES, OPTIONS)
82
83           See "Constructing a message" in Mail::Message::Construct::Read
84
85       $obj->rebuild(OPTIONS)
86
87           See "Constructing a message" in Mail::Message::Construct::Rebuild
88
89       $obj->reply(OPTIONS)
90
91           See "Constructing a message" in Mail::Message::Construct::Reply
92
93       $obj->replyPrelude([STRING⎪FIELD⎪ADDRESS⎪ARRAY-OF-THINGS])
94
95           See "Constructing a message" in Mail::Message::Construct::Reply
96
97       $obj->replySubject(STRING)
98
99       Mail::Box::Maildir::Message->replySubject(STRING)
100
101           See "Constructing a message" in Mail::Message::Construct::Reply
102
103       The message
104
105       $obj->container
106
107           See "The message" in Mail::Message
108
109       $obj->copyTo(FOLDER, OPTIONS)
110
111           See "The message" in Mail::Box::Message
112
113       $obj->filename([FILENAME])
114
115           Returns the current filename for this message.  If the FILENAME
116           argument is specified, a new filename will be set.  For maildir
117           messages this means that modifications are immediately performed:
118           there will be a rename (move) from the old name to the new name.
119           Labels may change within in the message object as well.
120
121       $obj->folder([FOLDER])
122
123           See "The message" in Mail::Box::Message
124
125       $obj->isDummy
126
127           See "The message" in Mail::Message
128
129       $obj->isPart
130
131           See "The message" in Mail::Message
132
133       $obj->messageId
134
135           See "The message" in Mail::Message
136
137       $obj->moveTo(FOLDER, OPTIONS)
138
139           See "The message" in Mail::Box::Message
140
141       $obj->print([FILEHANDLE])
142
143           See "The message" in Mail::Message
144
145       $obj->send([MAILER], OPTIONS)
146
147           See "The message" in Mail::Message
148
149       $obj->seqnr([INTEGER])
150
151           See "The message" in Mail::Box::Message
152
153       $obj->size
154
155           See "The message" in Mail::Message
156
157       $obj->toplevel
158
159           See "The message" in Mail::Message
160
161       $obj->write([FILEHANDLE])
162
163           See "The message" in Mail::Message
164
165       The header
166
167       $obj->bcc
168
169           See "The header" in Mail::Message
170
171       $obj->cc
172
173           See "The header" in Mail::Message
174
175       $obj->date
176
177           See "The header" in Mail::Message
178
179       $obj->destinations
180
181           See "The header" in Mail::Message
182
183       $obj->from
184
185           See "The header" in Mail::Message
186
187       $obj->get(FIELDNAME)
188
189           See "The header" in Mail::Message
190
191       $obj->guessTimestamp
192
193           The filename of a "Mail::Box::Maildir::Message" contains a time‐
194           stamp.  This is a wild guess about the actual time of sending of
195           the message: it is the time of receipt which may be seconds to
196           hours off.  But is still a good guess...  When the message header
197           is not parsed, then this date is used.
198
199       $obj->head([HEAD])
200
201           See "The header" in Mail::Message
202
203       $obj->nrLines
204
205           See "The header" in Mail::Message
206
207       $obj->sender
208
209           See "The header" in Mail::Message
210
211       $obj->study(FIELDNAME)
212
213           See "The header" in Mail::Message
214
215       $obj->subject
216
217           See "The header" in Mail::Message
218
219       $obj->timestamp
220
221           See "The header" in Mail::Message
222
223       $obj->to
224
225           See "The header" in Mail::Message
226
227       The body
228
229       $obj->body([BODY])
230
231           See "The body" in Mail::Message
232
233       $obj->decoded(OPTIONS)
234
235           See "The body" in Mail::Message
236
237       $obj->encode(OPTIONS)
238
239           See "The body" in Mail::Message
240
241       $obj->isMultipart
242
243           See "The body" in Mail::Message
244
245       $obj->isNested
246
247           See "The body" in Mail::Message
248
249       $obj->parts(['ALL'⎪'ACTIVE'⎪'DELETED'⎪'RECURSE'⎪FILTER])
250
251           See "The body" in Mail::Message
252
253       Flags
254
255       $obj->delete
256
257           See "Flags" in Mail::Message
258
259       $obj->deleted([BOOLEAN])
260
261           See "Flags" in Mail::Message
262
263       $obj->isDeleted
264
265           See "Flags" in Mail::Message
266
267       $obj->isModified
268
269           See "Flags" in Mail::Message
270
271       $obj->label(LABEL⎪PAIRS)
272
273           See "Flags" in Mail::Message
274
275       $obj->labels
276
277           See "Flags" in Mail::Message
278
279       $obj->labelsToStatus
280
281           See "Flags" in Mail::Message
282
283       $obj->modified([BOOLEAN])
284
285           See "Flags" in Mail::Message
286
287       $obj->statusToLabels
288
289           See "Flags" in Mail::Message
290
291       The whole message as text
292
293       $obj->file
294
295           See "The whole message as text" in Mail::Message::Construct::Text
296
297       $obj->lines
298
299           See "The whole message as text" in Mail::Message::Construct::Text
300
301       $obj->printStructure([FILEHANDLE⎪undef],[INDENT])
302
303           See "The whole message as text" in Mail::Message::Construct::Text
304
305       $obj->string
306
307           See "The whole message as text" in Mail::Message::Construct::Text
308
309       Labels
310
311       $obj->labelsToFilename
312
313           When the labels on a message change, this may implicate a change in
314           the message's filename.  The change will take place immediately.
315           The new filename (which may be the same as the old filename) is
316           returned.  "undef" is returned when the rename is required but
317           fails.
318
319       Internals
320
321       $obj->accept([BOOLEAN])
322
323           Accept a message for the folder.  This will move it from the "new"
324           or "tmp" sub-directories into the "cur" sub-directory (or back when
325           the BOOLEAN is "false").  When you accept an already accepted mes‐
326           sage, nothing will happen.
327
328       $obj->clonedFrom
329
330           See "Internals" in Mail::Message
331
332       Mail::Box::Maildir::Message->coerce(MESSAGE, OPTIONS)
333
334           See "Internals" in Mail::Message
335
336       $obj->create(FILENAME)
337
338           See "Internals" in Mail::Box::Dir::Message
339
340       $obj->diskDelete
341
342           See "Internals" in Mail::Box::Message
343
344       $obj->isDelayed
345
346           See "Internals" in Mail::Message
347
348       $obj->loadBody
349
350           See "Internals" in Mail::Box::Dir::Message
351
352       $obj->loadHead
353
354           See "Internals" in Mail::Box::Dir::Message
355
356       $obj->parser
357
358           See "Internals" in Mail::Box::Dir::Message
359
360       $obj->readBody(PARSER, HEAD [, BODYTYPE])
361
362           See "Internals" in Mail::Box::Message
363
364       $obj->readFromParser(PARSER, [BODYTYPE])
365
366           See "Internals" in Mail::Message
367
368       $obj->readHead(PARSER [,CLASS])
369
370           See "Internals" in Mail::Message
371
372       $obj->recursiveRebuildPart(PART, OPTIONS)
373
374           See "Internals" in Mail::Message::Construct::Rebuild
375
376       $obj->storeBody(BODY)
377
378           See "Internals" in Mail::Message
379
380       $obj->takeMessageId([STRING])
381
382           See "Internals" in Mail::Message
383
384       Error handling
385
386       $obj->AUTOLOAD
387
388           See "METHODS" in Mail::Message::Construct
389
390       $obj->addReport(OBJECT)
391
392           See "Error handling" in Mail::Reporter
393
394       $obj->defaultTrace([LEVEL]⎪[LOGLEVEL, TRACELEVEL]⎪[LEVEL, CALLBACK])
395
396       Mail::Box::Maildir::Message->defaultTrace([LEVEL]⎪[LOGLEVEL,
397       TRACELEVEL]⎪[LEVEL, CALLBACK])
398
399           See "Error handling" in Mail::Reporter
400
401       $obj->errors
402
403           See "Error handling" in Mail::Reporter
404
405       $obj->log([LEVEL [,STRINGS]])
406
407       Mail::Box::Maildir::Message->log([LEVEL [,STRINGS]])
408
409           See "Error handling" in Mail::Reporter
410
411       $obj->logPriority(LEVEL)
412
413       Mail::Box::Maildir::Message->logPriority(LEVEL)
414
415           See "Error handling" in Mail::Reporter
416
417       $obj->logSettings
418
419           See "Error handling" in Mail::Reporter
420
421       $obj->notImplemented
422
423           See "Error handling" in Mail::Reporter
424
425       $obj->report([LEVEL])
426
427           See "Error handling" in Mail::Reporter
428
429       $obj->reportAll([LEVEL])
430
431           See "Error handling" in Mail::Reporter
432
433       $obj->shortSize([VALUE])
434
435       Mail::Box::Maildir::Message->shortSize([VALUE])
436
437           See "Error handling" in Mail::Message
438
439       $obj->shortString
440
441           See "Error handling" in Mail::Message
442
443       $obj->trace([LEVEL])
444
445           See "Error handling" in Mail::Reporter
446
447       $obj->warnings
448
449           See "Error handling" in Mail::Reporter
450
451       Cleanup
452
453       $obj->DESTROY
454
455           See "Cleanup" in Mail::Message
456
457       $obj->destruct
458
459           See "Cleanup" in Mail::Box::Message
460
461       $obj->inGlobalDestruction
462
463           See "Cleanup" in Mail::Reporter
464

DETAILS

466       Labels
467
468       Flags in filename
469
470       When new messages arrive on system and have to be stored in a maildir
471       folder, they are put in the "new" sub-directory of the folder (first
472       created in the "tmp" sub-directory and then immediately moved to
473       "new").  The following information was found at
474       <http://cr.yp.to/proto/maildir.html>.
475
476       Each message is written in a separate file.  The filename is con‐
477       structed from the time-of-arrival, a hostname, an unique component, a
478       syntax marker, and flags. For example "1014220791.meteor.42:2,DF".  The
479       filename must match:
480
481        my ($time, $unique, $hostname, $info)
482           = $filename =~ m!^(\d+)\.(.*)\.(\w+)(\:.*)?$!;
483        my ($semantics, $flags)
484           = $info =~ m!([12])\,([DFPRST]*)$!;
485        my @flags = split //, $flags;
486
487       When an application opens the folder, there may be messages in "new"
488       which are new arival, and messages in "cur".  The latter are labeled
489       "accepted".  To move a message from "new" to "cur", you have two
490       options with the same effect:
491
492         $msg->accept;
493         $msg->label(accept => 1);
494
495       See accept(), label(), Mail::Box::Maildir::new(accept_new), and
496       Mail::Box::Maildir::acceptMessages()
497
498       The messages are moved, and their name is immediately extended with
499       flags.  An example:
500
501        new/897979431.meteor.42      may become
502        cur/897979431.meteor.42:2,FS
503
504       The added characters ':2,' refer to the "second state of processing",
505       where the message has been inspected.  And the characters (which should
506       be in alphabetic order) mean
507
508        D      => draft
509        F      => flagged
510        R      => replied  (answered)
511        S      => seen
512        T      => deleted  (tagged for deletion)
513
514       Some maildir clients support
515        P      => passed   (resent/forwarded/bounced to someone else)
516
517       The flags will immediately change when label() or delete() is used,
518       which differs from other message implementations: maildir is stateless,
519       and should not break when applications crash.
520

DIAGNOSTICS

522       Error: Cannot create parser for $filename.
523
524       For some reason (the previous message have told you already) it was not
525       possible to create a message parser for the specified filename.
526
527       Error: Cannot include forward source as $include.
528
529       Unknown alternative for the forward(include).  Valid choices are "NO",
530       "INLINE", "ATTACH", and "ENCAPSULATE".
531
532       Error: Cannot include reply source as $include.
533
534       Unknown alternative for the "include" option of reply().  Valid choices
535       are "NO", "INLINE", and "ATTACH".
536
537       Error: Cannot write message to $filename: $!
538
539       When a modified or new message is written to disk, it is first written
540       to a temporary file in the folder directory.  For some reason, it is
541       impossible to create this file.
542
543       Error: Failed to move $new to $filename: $!
544
545       When a modified or new message is written to disk, it is first written
546       to a temporary file in the folder directory.  Then, the new file is
547       moved to replace the existing file.  Apparently, the latter fails.
548
549       Error: Method bounce requires To, Cc, or Bcc
550
551       The message bounce() method forwards a received message off to someone
552       else without modification; you must specified it's new destination.  If
553       you have the urge not to specify any destination, you probably are
554       looking for reply(). When you wish to modify the content, use for‐
555       ward().
556
557       Error: Method forwardAttach requires a preamble
558
559       Error: Method forwardEncapsulate requires a preamble
560
561       Error: No address to create forwarded to.
562
563       If a forward message is created, a destination address must be speci‐
564       fied.
565
566       Error: No default mailer found to send message.
567
568       The message send() mechanism had not enough information to automati‐
569       cally find a mail transfer agent to sent this message.  Specify a
570       mailer explicitly using the "via" options.
571
572       Error: No rebuild rule $name defined.
573
574       Error: Only build() Mail::Message's; they are not in a folder yet
575
576       You may wish to construct a message to be stored in a some kind of
577       folder, but you need to do that in two steps.  First, create a normal
578       Mail::Message, and then add it to the folder.  During this
579       Mail::Box::addMessage() process, the message will get coerce()-d into
580       the right message type, adding storage information and the like.
581
582       Error: Package $package does not implement $method.
583
584       Fatal error: the specific package (or one of its superclasses) does not
585       implement this method where it should. This message means that some
586       other related classes do implement this method however the class at
587       hand does not.  Probably you should investigate this and probably
588       inform the author of the package.
589
590       Error: Unable to read delayed body.
591
592       For some reason, the header of the message could be read, but the body
593       cannot.  Probably the file has disappeared or the permissions were
594       changed during the progress of the program.
595
596       Error: Unable to read delayed head.
597
598       Mail::Box tries to be lazy with respect to parsing messages.  When a
599       directory organized folder is opened, only the filenames of messages
600       are collected.  At first use, the messages are read from their file.
601       Apperently, a message is used for the first time here, but has disap‐
602       peared or is unreadible for some other reason.
603

LICENSE

609       Copyrights 2001-2007 by Mark Overmeer.For other contributors see
610       ChangeLog.
611
612       This program is free software; you can redistribute it and/or modify it
613       under the same terms as Perl itself.  See
614       http://www.perl.com/perl/misc/Artistic.html
615
616
617
618perl v5.8.8                       2007-03-25    Mail::Box::Maildir::Message(3)