1Mail::Box::Message(3) User Contributed Perl DocumentationMail::Box::Message(3)
2
3
4

NAME

6       Mail::Box::Message - manage one message within a mail-folder
7

INHERITANCE

9        Mail::Box::Message
10          is a Mail::Message
11          is a Mail::Reporter
12
13        Mail::Box::Message is extended by
14          Mail::Box::Dir::Message
15          Mail::Box::File::Message
16          Mail::Box::Message::Destructed
17          Mail::Box::Net::Message
18

SYNOPSIS

20        # Usually these message objects are created indirectly
21        use Mail::Box::Manager;
22        my $manager = Mail::Box::Manager->new;
23        my $folder  = $manager->open(folder => 'Mail/Drafts');
24        my $msg     = $folder->message(1);
25        $msg->delete;
26        $msg->size;   # and much more
27

DESCRIPTION

29       These pages do only describe methods which relate to folders.  If you
30       access the knowledge of a message, then read Mail::Message.
31
32       During its life, a message will pass through certain stages.  These
33       stages were introduced to reduce the access-time to the folder.
34       Changing from stage, the message's body and head objects may change.
35

METHODS

37   Constructors
38       $obj->clone(OPTIONS)
39           See "Constructors" in Mail::Message
40
41       Mail::Box::Message->new(OPTIONS)
42            -Option    --Defined in     --Default
43             body        Mail::Message    undef
44             body_type                    <from folder>
45             deleted     Mail::Message    <false>
46             field_type  Mail::Message    undef
47             folder                       <required>
48             head        Mail::Message    undef
49             head_type   Mail::Message    Mail::Message::Head::Complete
50             labels      Mail::Message    {}
51             log         Mail::Reporter   'WARNINGS'
52             messageId   Mail::Message    undef
53             modified    Mail::Message    <false>
54             size                         undef
55             trace       Mail::Reporter   'WARNINGS'
56             trusted     Mail::Message    <false>
57
58           body => OBJECT
59           body_type => CODE|CLASS
60             If the body of a message is used delay-loaded, the message must
61             what type of message to become when it finally gets parsed.  The
62             folder which is delaying the load must specify the algorithm to
63             determine that type.
64
65           deleted => BOOLEAN
66           field_type => CLASS
67           folder => FOLDER
68             The folder where this message appeared in.  The argument is an
69             instance of (a sub-class of) a Mail::Box.
70
71           head => OBJECT
72           head_type => CLASS
73           labels => ARRAY|HASH
74           log => LEVEL
75           messageId => STRING
76           modified => BOOLEAN
77           size => INTEGER
78             The size of the message, which includes head and body, but
79             without the message separators which may be used by the folder
80             type.
81
82           trace => LEVEL
83           trusted => BOOLEAN
84
85   Constructing a message
86       $obj->bounce([RG-OBJECT|OPTIONS])
87           See "Constructing a message" in Mail::Message::Construct::Bounce
88
89       Mail::Box::Message->build([MESSAGE|PART|BODY], CONTENT)
90           See "Constructing a message" in Mail::Message::Construct::Build
91
92       Mail::Box::Message->buildFromBody(BODY, [HEAD], HEADERS)
93           See "Constructing a message" in Mail::Message::Construct::Build
94
95       $obj->forward(OPTIONS)
96           See "Constructing a message" in Mail::Message::Construct::Forward
97
98       $obj->forwardAttach(OPTIONS)
99           See "Constructing a message" in Mail::Message::Construct::Forward
100
101       $obj->forwardEncapsulate(OPTIONS)
102           See "Constructing a message" in Mail::Message::Construct::Forward
103
104       $obj->forwardInline(OPTIONS)
105           See "Constructing a message" in Mail::Message::Construct::Forward
106
107       $obj->forwardNo(OPTIONS)
108           See "Constructing a message" in Mail::Message::Construct::Forward
109
110       $obj->forwardPostlude
111           See "Constructing a message" in Mail::Message::Construct::Forward
112
113       $obj->forwardPrelude
114           See "Constructing a message" in Mail::Message::Construct::Forward
115
116       $obj->forwardSubject(STRING)
117           See "Constructing a message" in Mail::Message::Construct::Forward
118
119       Mail::Box::Message->read(FILEHANDLE|SCALAR|REF-SCALAR|ARRAY-OF-LINES,
120       OPTIONS)
121           See "Constructing a message" in Mail::Message::Construct::Read
122
123       $obj->rebuild(OPTIONS)
124           See "Constructing a message" in Mail::Message::Construct::Rebuild
125
126       $obj->reply(OPTIONS)
127           See "Constructing a message" in Mail::Message::Construct::Reply
128
129       $obj->replyPrelude([STRING|FIELD|ADDRESS|ARRAY-OF-THINGS])
130           See "Constructing a message" in Mail::Message::Construct::Reply
131
132       $obj->replySubject(STRING)
133           Mail::Box::Message->replySubject(STRING)
134
135           See "Constructing a message" in Mail::Message::Construct::Reply
136
137   The message
138       $obj->container
139           See "The message" in Mail::Message
140
141       $obj->copyTo(FOLDER, OPTIONS)
142           Copy the message to the indicated opened FOLDER, without deleting
143           the original.  The coerced message (the clone in the destination
144           folder) is returned.
145
146            -Option      --Default
147             shallow       <false>
148             shallow_body  <false>
149             shallow_head  <false>
150             share         <false>
151
152           shallow => BOOLEAN
153             Used for clone(shallow).
154
155           shallow_body => BOOLEAN
156             Used for clone(shallow_body).
157
158           shallow_head => BOOLEAN
159             Used for clone(shallow_head).
160
161           share => BOOLEAN
162             Try to share the physical storage of the message between the two
163             folders.  Sometimes, they even may be of different types.  When
164             not possible, this options will be silently ignored.
165
166           example:
167
168            my $draft = $mgr->open(folder => 'Draft');
169            $message->copyTo($draft, share => 1);
170
171       $obj->folder([FOLDER])
172           In with folder did we detect this message/dummy?  This is a
173           reference to the folder-object.
174
175       $obj->isDummy
176           See "The message" in Mail::Message
177
178       $obj->isPart
179           See "The message" in Mail::Message
180
181       $obj->messageId
182           See "The message" in Mail::Message
183
184       $obj->moveTo(FOLDER, OPTIONS)
185           Move the message from this folder to the FOLDER specified.  This
186           will create a copy using clone() first.  Then, this original
187           message is flagged to get deleted.  So until the source folder is
188           closed, two copies of the message may stay in memory.
189
190           The newly created message clone (part of the destination folder) is
191           returned.  All OPTIONS are passed to copyTo()
192
193            -Option      --Default
194             shallow_body  <undef>
195             share         <true unless shallow_body exists>
196
197           shallow_body => BOOLEAN
198             Only create a shallow body, which means that the header can not
199             be reused.  A message can therefore not be shared in storage
200             unless explicitly stated.
201
202           share => BOOLEAN
203             When there is a chance that the original message can be
204             undeleted, then this must be set to false.  Otherwise a shallow
205             clone will be made, which will share the header which can be
206             modified in the undeleted message.
207
208           example: of moving a message
209
210            my $t = $msg->moveTo('trash');
211
212           is equivalent to
213
214            my $t = $msg->copyTo('trash', share => 1);
215            $msg->delete;
216
217       $obj->print([FILEHANDLE])
218           See "The message" in Mail::Message
219
220       $obj->send([MAILER], OPTIONS)
221           See "The message" in Mail::Message
222
223       $obj->seqnr([INTEGER])
224           Get the number of this message is the current folder.  It starts
225           counting from zero.  Do not change the number.
226
227       $obj->size
228           See "The message" in Mail::Message
229
230       $obj->toplevel
231           See "The message" in Mail::Message
232
233       $obj->write([FILEHANDLE])
234           See "The message" in Mail::Message
235
236   The header
237       $obj->bcc
238           See "The header" in Mail::Message
239
240       $obj->cc
241           See "The header" in Mail::Message
242
243       $obj->date
244           See "The header" in Mail::Message
245
246       $obj->destinations
247           See "The header" in Mail::Message
248
249       $obj->from
250           See "The header" in Mail::Message
251
252       $obj->get(FIELDNAME)
253           See "The header" in Mail::Message
254
255       $obj->guessTimestamp
256           See "The header" in Mail::Message
257
258       $obj->head([HEAD])
259           See "The header" in Mail::Message
260
261       $obj->nrLines
262           See "The header" in Mail::Message
263
264       $obj->sender
265           See "The header" in Mail::Message
266
267       $obj->study(FIELDNAME)
268           See "The header" in Mail::Message
269
270       $obj->subject
271           See "The header" in Mail::Message
272
273       $obj->timestamp
274           See "The header" in Mail::Message
275
276       $obj->to
277           See "The header" in Mail::Message
278
279   The body
280       $obj->body([BODY])
281           See "The body" in Mail::Message
282
283       $obj->contentType
284           See "The body" in Mail::Message
285
286       $obj->decoded(OPTIONS)
287           See "The body" in Mail::Message
288
289       $obj->encode(OPTIONS)
290           See "The body" in Mail::Message
291
292       $obj->isMultipart
293           See "The body" in Mail::Message
294
295       $obj->isNested
296           See "The body" in Mail::Message
297
298       $obj->parts(['ALL'|'ACTIVE'|'DELETED'|'RECURSE'|FILTER])
299           See "The body" in Mail::Message
300
301   Flags
302       $obj->delete
303           See "Flags" in Mail::Message
304
305       $obj->deleted([BOOLEAN])
306           See "Flags" in Mail::Message
307
308       $obj->isDeleted
309           See "Flags" in Mail::Message
310
311       $obj->isModified
312           See "Flags" in Mail::Message
313
314       $obj->label(LABEL|PAIRS)
315           See "Flags" in Mail::Message
316
317       $obj->labels
318           See "Flags" in Mail::Message
319
320       $obj->labelsToStatus
321           See "Flags" in Mail::Message
322
323       $obj->modified([BOOLEAN])
324           See "Flags" in Mail::Message
325
326       $obj->statusToLabels
327           See "Flags" in Mail::Message
328
329   The whole message as text
330       $obj->file
331           See "The whole message as text" in Mail::Message::Construct::Text
332
333       $obj->lines
334           See "The whole message as text" in Mail::Message::Construct::Text
335
336       $obj->printStructure([FILEHANDLE|undef],[INDENT])
337           See "The whole message as text" in Mail::Message::Construct::Text
338
339       $obj->string
340           See "The whole message as text" in Mail::Message::Construct::Text
341
342   Internals
343       $obj->clonedFrom
344           See "Internals" in Mail::Message
345
346       Mail::Box::Message->coerce(MESSAGE, OPTIONS)
347           See "Internals" in Mail::Message
348
349       $obj->diskDelete
350           Remove a message from disk.  This is not from the folder, but
351           everything else, like parts of the message which are stored outside
352           from the folder.
353
354       $obj->isDelayed
355           See "Internals" in Mail::Message
356
357       $obj->readBody(PARSER, HEAD [, BODYTYPE])
358           Read the body of one message.  The PARSER gives access to the
359           folder file.  The HEAD has been read with readHead().  The optional
360           BODYTYPE supplies the class name of the body to be created, or a
361           code reference to a routine which can produce a body type based on
362           the head (passed as first argument).
363
364           By default, the BODYTYPE will call Mail::Box::determineBodyType()
365           where the message will be added to.
366
367       $obj->readFromParser(PARSER, [BODYTYPE])
368           See "Internals" in Mail::Message
369
370       $obj->readHead(PARSER [,CLASS])
371           See "Internals" in Mail::Message
372
373       $obj->recursiveRebuildPart(PART, OPTIONS)
374           See "Internals" in Mail::Message::Construct::Rebuild
375
376       $obj->storeBody(BODY)
377           See "Internals" in Mail::Message
378
379       $obj->takeMessageId([STRING])
380           See "Internals" in Mail::Message
381
382   Error handling
383       $obj->AUTOLOAD
384           See "METHODS" in Mail::Message::Construct
385
386       $obj->addReport(OBJECT)
387           See "Error handling" in Mail::Reporter
388
389       $obj->defaultTrace([LEVEL]|[LOGLEVEL, TRACELEVEL]|[LEVEL, CALLBACK])
390           Mail::Box::Message->defaultTrace([LEVEL]|[LOGLEVEL,
391           TRACELEVEL]|[LEVEL, CALLBACK])
392
393           See "Error handling" in Mail::Reporter
394
395       $obj->errors
396           See "Error handling" in Mail::Reporter
397
398       $obj->log([LEVEL [,STRINGS]])
399           Mail::Box::Message->log([LEVEL [,STRINGS]])
400
401           See "Error handling" in Mail::Reporter
402
403       $obj->logPriority(LEVEL)
404           Mail::Box::Message->logPriority(LEVEL)
405
406           See "Error handling" in Mail::Reporter
407
408       $obj->logSettings
409           See "Error handling" in Mail::Reporter
410
411       $obj->notImplemented
412           See "Error handling" in Mail::Reporter
413
414       $obj->report([LEVEL])
415           See "Error handling" in Mail::Reporter
416
417       $obj->reportAll([LEVEL])
418           See "Error handling" in Mail::Reporter
419
420       $obj->shortSize([VALUE])
421           Mail::Box::Message->shortSize([VALUE])
422
423           See "Error handling" in Mail::Message
424
425       $obj->shortString
426           See "Error handling" in Mail::Message
427
428       $obj->trace([LEVEL])
429           See "Error handling" in Mail::Reporter
430
431       $obj->warnings
432           See "Error handling" in Mail::Reporter
433
434   Cleanup
435       $obj->DESTROY
436           See "Cleanup" in Mail::Message
437
438       $obj->destruct
439           Removes most of the memory occupied by the message by detaching the
440           header and body.  Then, the object changes into a
441           Mail::Box::Message::Destructed which will catch all attempts to
442           access the header and body.  Be careful with the usage of this
443           method.
444
445       $obj->inGlobalDestruction
446           See "Cleanup" in Mail::Reporter
447

DIAGNOSTICS

449       Error: Cannot coerce a $class object into a $class object
450       Error: Cannot include forward source as $include.
451           Unknown alternative for the forward(include).  Valid choices are
452           "NO", "INLINE", "ATTACH", and "ENCAPSULATE".
453
454       Error: Cannot include reply source as $include.
455           Unknown alternative for the "include" option of reply().  Valid
456           choices are "NO", "INLINE", and "ATTACH".
457
458       Error: Method bounce requires To, Cc, or Bcc
459           The message bounce() method forwards a received message off to
460           someone else without modification; you must specified it's new
461           destination.  If you have the urge not to specify any destination,
462           you probably are looking for reply(). When you wish to modify the
463           content, use forward().
464
465       Error: Method forwardAttach requires a preamble
466       Error: Method forwardEncapsulate requires a preamble
467       Error: No address to create forwarded to.
468           If a forward message is created, a destination address must be
469           specified.
470
471       Error: No default mailer found to send message.
472           The message send() mechanism had not enough information to
473           automatically find a mail transfer agent to sent this message.
474           Specify a mailer explicitly using the "via" options.
475
476       Error: No rebuild rule $name defined.
477       Error: Only build() Mail::Message's; they are not in a folder yet
478           You may wish to construct a message to be stored in a some kind of
479           folder, but you need to do that in two steps.  First, create a
480           normal Mail::Message, and then add it to the folder.  During this
481           Mail::Box::addMessage() process, the message will get coerce()-d
482           into the right message type, adding storage information and the
483           like.
484
485       Error: Package $package does not implement $method.
486           Fatal error: the specific package (or one of its superclasses) does
487           not implement this method where it should. This message means that
488           some other related classes do implement this method however the
489           class at hand does not.  Probably you should investigate this and
490           probably inform the author of the package.
491
492       Error: coercion starts with some object
493

SEE ALSO

495       This module is part of Mail-Box distribution version 2.097, built on
496       January 26, 2011. Website: http://perl.overmeer.net/mailbox/
497

LICENSE

499       Copyrights 2001-2011 by Mark Overmeer. For other contributors see
500       ChangeLog.
501
502       This program is free software; you can redistribute it and/or modify it
503       under the same terms as Perl itself.  See
504       http://www.perl.com/perl/misc/Artistic.html
505
506
507
508perl v5.12.3                      2011-01-26             Mail::Box::Message(3)
Impressum