Mail::Message::Body::Multipart(3pm)

1Mail::Message::Body::MuUlsteirpaCrotn(t3r)ibuted Perl DoMcauimle:n:tMaetsisoange::Body::Multipart(3)
2
3
4

NAME

6       Mail::Message::Body::Multipart - body of a message with attachments
7

INHERITANCE

9        Mail::Message::Body::Multipart
10          is a Mail::Message::Body
11          is a Mail::Reporter
12

SYNOPSIS

14        See Mail::Message::Body
15
16        if($body->isMultipart) {
17           my @attachments = $body->parts;
18           my $attachment3 = $body->part(2);
19           my $before      = $body->preamble;
20           my $after       = $body->epilogue;
21           $body->part(1)->delete;
22        }
23

DESCRIPTION

25       The body (content) of a message can be stored in various ways.  In this
26       manual-page you find the description of extra functionality you have
27       when a message contains attachments (parts).
28

OVERLOADED

30       overload: ""
31
32           See "OVERLOADED" in Mail::Message::Body
33
34       overload: '==' and '!='
35
36           See "OVERLOADED" in Mail::Message::Body
37
38       overload: @{}
39
40           See "OVERLOADED" in Mail::Message::Body
41
42       overload: bool
43
44           See "OVERLOADED" in Mail::Message::Body
45

METHODS

47       Constructors
48
49       $obj->clone
50
51           See "Constructors" in Mail::Message::Body
52
53       Mail::Message::Body::Multipart->new(OPTIONS)
54
55        Option           --Defined in     --Default
56        based_on           Mail::Message::Body  undef
57        boundary                            undef
58        charset            Mail::Message::Body  'us-ascii'
59        checked            Mail::Message::Body  <false>
60        data               Mail::Message::Body  undef
61        description        Mail::Message::Body  undef
62        disposition        Mail::Message::Body  undef
63        eol                Mail::Message::Body  'NATIVE'
64        epilogue                            undef
65        file               Mail::Message::Body  undef
66        log                Mail::Reporter   'WARNINGS'
67        message            Mail::Message::Body  undef
68        mime_type          Mail::Message::Body  'multipart/mixed'
69        modified           Mail::Message::Body  <false>
70        parts                               undef
71        preamble                            undef
72        trace              Mail::Reporter   'WARNINGS'
73        transfer_encoding  Mail::Message::Body  'none'
74
75           . based_on BODY
76
77           . boundary STRING
78
79               Separator to be used between parts of the message.  This sepa‐
80               rator must be unique in case the message contains nested multi‐
81               parts (which are not unusual).  If "undef", a nice unique
82               boundary will be generated.
83
84           . charset STRING
85
86           . checked BOOLEAN
87
88           . data ARRAY-OF-LINES ⎪ STRING
89
90           . description STRING⎪FIELD
91
92           . disposition STRING⎪FIELD
93
94           . eol 'CR'⎪'LF'⎪'CRLF'⎪'NATIVE'
95
96           . epilogue BODY⎪STRING
97
98               The text which is included in the main body after the final
99               boundary.  This is usually empty, and has no meaning.
100
101               Provide a BODY object or a STRING which will automatically
102               translated into a "text/plain" body.
103
104           . file FILENAME⎪FILEHANDLE⎪IOHANDLE
105
106           . log LEVEL
107
108           . message MESSAGE
109
110           . mime_type STRING⎪FIELD⎪MIME
111
112           . modified BOOLEAN
113
114           . parts ARRAY-OF-(MESSAGES⎪BODIES)
115
116               Specifies an initial list of parts in this body.  These may be
117               full MESSAGES, or BODIES which transformed into messages before
118               use.  Each message is coerced into a Mail::Message::Part
119               object.
120
121               MIME::Entity and Mail::Internet objects are acceptable in the
122               list, because they are coercible into Mail::Message::Part's.
123               Values of "undef" will be skipped silently.
124
125           . preamble BODY⎪STRING
126
127               The text which is included in the body before the first part.
128               It is common use to include a text to warn the user that the
129               message is a multipart.  However, this was useful in earlier
130               days: most mail agents are very capable in warning the user
131               themselves.
132
133               Provide a BODY object or a STRING which will automatically
134               translated into a text/plain body.
135
136           . trace LEVEL
137
138           . transfer_encoding STRING⎪FIELD
139
140           Example:
141
142            my $intro = Mail::Message::Body->new(data => ['part one']);
143            my $pgp   = Mail::Message::Body->new(data => ['part three']);
144
145            my $body  = Mail::Message::Body::Multipart->new
146              ( boundary => time . '--it-s-mine'
147              , preamble => "This is a multi-part message in MIME format.\n\n"
148              , parts    => [ $intro, $folder->message(3)->decoded, $pgp ]
149              );
150
151       Constructing a body
152
153       $obj->attach(MESSAGES⎪BODIES)
154
155           Attach a list of MESSAGES to this multipart.  A new body is
156           returned.  When you specify BODIES, they will first be translated
157           into real messages.  MIME::Entity and Mail::Internet objects may be
158           specified too.  In any case, the parts will be coerced into
159           Mail::Message::Part's.
160
161       $obj->check
162
163           See "Constructing a body" in Mail::Message::Body::Encode
164
165       $obj->concatenate(COMPONENTS)
166
167           See "Constructing a body" in Mail::Message::Body::Construct
168
169       $obj->decoded(OPTIONS)
170
171           See "Constructing a body" in Mail::Message::Body
172
173       $obj->encode(OPTIONS)
174
175           See "Constructing a body" in Mail::Message::Body::Encode
176
177       $obj->encoded
178
179           See "Constructing a body" in Mail::Message::Body::Encode
180
181       $obj->eol(['CR'⎪'LF'⎪'CRLF'⎪'NATIVE'])
182
183           See "Constructing a body" in Mail::Message::Body
184
185       $obj->foreachComponent(CODE)
186
187           Execute the CODE for each component of the message: the preamble,
188           the epilogue, and each of the parts.
189
190           Each component is a body and is passed as second argument to the
191           CODE.  The first argument is a reference to this multi-parted body.
192           The CODE returns a body object.  When any of the returned bodies
193           differs from the body which was passed, then a new multi-part body
194           will be returned.  Reference to the not-changed bodies and the
195           changed bodies will be included in that new multi-part.
196
197           Example:
198
199            my $checked = $multi->foreachComponent(sub {$_[1]->check});
200
201       $obj->foreachLine((CODE))
202
203           It is NOT possible to call some code for each line of a multipart,
204           because that would not only inflict damage to the body of each mes‐
205           sage part, but also to the headers and the part separators.
206
207       $obj->stripSignature(OPTIONS)
208
209           Removes all parts which contains data usually defined as being sig‐
210           nature.  The MIME::Type module provides this knowledge.  A new mul‐
211           tipart is returned, containing the remaining parts.  No OPTIONS are
212           defined yet, although some may be specified, because this method
213           overrules the "stripSignature" method for normal bodies.
214
215            Option     --Defined in     --Default
216            max_lines    Mail::Message::Body::Construct  10
217            pattern      Mail::Message::Body::Construct  qr/^--\s?$/
218            result_type  Mail::Message::Body::Construct  <same as current>
219
220           . max_lines INTEGER⎪undef
221
222           . pattern REGEX⎪STRING⎪CODE
223
224           . result_type CLASS
225
226       $obj->unify(BODY)
227
228           See "Constructing a body" in Mail::Message::Body::Encode
229
230       The body
231
232       $obj->isDelayed
233
234           See "The body" in Mail::Message::Body
235
236       $obj->isMultipart
237
238           See "The body" in Mail::Message::Body
239
240       $obj->isNested
241
242           See "The body" in Mail::Message::Body
243
244       $obj->message([MESSAGE])
245
246           See "The body" in Mail::Message::Body
247
248       About the payload
249
250       $obj->charset
251
252           See "About the payload" in Mail::Message::Body
253
254       $obj->checked([BOOLEAN])
255
256           See "About the payload" in Mail::Message::Body
257
258       $obj->description([STRING⎪FIELD])
259
260           See "About the payload" in Mail::Message::Body
261
262       $obj->disposition([STRING⎪FIELD])
263
264           See "About the payload" in Mail::Message::Body
265
266       $obj->dispositionFilename([DIRECTORY])
267
268           See "About the payload" in Mail::Message::Body::Encode
269
270       $obj->isBinary
271
272           See "About the payload" in Mail::Message::Body::Encode
273
274       $obj->isText
275
276           See "About the payload" in Mail::Message::Body::Encode
277
278       $obj->mimeType
279
280           See "About the payload" in Mail::Message::Body
281
282       $obj->nrLines
283
284           See "About the payload" in Mail::Message::Body
285
286       $obj->size
287
288           See "About the payload" in Mail::Message::Body
289
290       $obj->transferEncoding([STRING⎪FIELD])
291
292           See "About the payload" in Mail::Message::Body
293
294       $obj->type([STRING⎪FIELD])
295
296           See "About the payload" in Mail::Message::Body
297
298       Access to the payload
299
300       $obj->boundary([STRING])
301
302           Returns the boundary which is used to separate the parts in this
303           body.  If none was read from file, then one will be assigned.  With
304           STRING you explicitly set the boundary to be used.
305
306       $obj->endsOnNewline
307
308           See "Access to the payload" in Mail::Message::Body
309
310       $obj->epilogue
311
312           Returns the epilogue; the text after the last message part (after
313           the last real attachment).  The epilogue is stored in a BODY
314           object, and its encoding is taken from the general multipart
315           header.
316
317       $obj->file
318
319           See "Access to the payload" in Mail::Message::Body
320
321       $obj->lines
322
323           See "Access to the payload" in Mail::Message::Body
324
325       $obj->part(INDEX)
326
327           Returns only the part with the specified INDEX.  You may use a neg‐
328           ative value here, which counts from the back in the list.  Parts
329           which are flagged to be deleted are included in the count.
330
331           Example:
332
333            $message->body->part(2)->print;
334            $body->part(1)->delete;
335
336       $obj->parts(['ALL'⎪'ACTIVE'⎪'DELETED'⎪'RECURSE'⎪FILTER])
337
338           Return all parts by default, or when ALL is specified.  "ACTIVE"
339           returns the parts which are not flagged for deletion, as opposite
340           to "DELETED".  "RECURSE" descents into all nested multiparts to
341           collect all parts.
342
343           You may also specify a code reference which is called for each
344           nested part.  The first argument will be the message part.  When
345           the code returns true, the part is incorporated in the return list.
346
347           Example:
348
349            print "Number of attachments: ",
350                scalar $message->body->parts('ACTIVE');
351
352            foreach my $part ($message->body->parts) {
353                print "Type: ", $part->get('Content-Type');
354            }
355
356       $obj->preamble
357
358           Returns the preamble; the text before the first message part
359           (before the first real attachment).  The preamble is stored in a
360           BODY object, and its encoding is taken from the multipart header.
361
362       $obj->print([FILEHANDLE])
363
364           See "Access to the payload" in Mail::Message::Body
365
366       $obj->printEscapedFrom(FILEHANDLE)
367
368           See "Access to the payload" in Mail::Message::Body
369
370       $obj->string
371
372           See "Access to the payload" in Mail::Message::Body
373
374       $obj->stripTrailingNewline
375
376           See "Access to the payload" in Mail::Message::Body
377
378       $obj->write(OPTIONS)
379
380           See "Access to the payload" in Mail::Message::Body
381
382       Internals
383
384       $obj->addTransferEncHandler(NAME, CLASS⎪OBJECT)
385
386       Mail::Message::Body::Multipart->addTransferEncHandler(NAME,
387       CLASS⎪OBJECT)
388
389           See "Internals" in Mail::Message::Body::Encode
390
391       $obj->contentInfoFrom(HEAD)
392
393           See "Internals" in Mail::Message::Body
394
395       $obj->contentInfoTo(HEAD)
396
397           See "Internals" in Mail::Message::Body
398
399       $obj->fileLocation([BEGIN,END])
400
401           See "Internals" in Mail::Message::Body
402
403       $obj->getTransferEncHandler(TYPE)
404
405           See "Internals" in Mail::Message::Body::Encode
406
407       $obj->isModified
408
409           See "Internals" in Mail::Message::Body
410
411       $obj->load
412
413           See "Internals" in Mail::Message::Body
414
415       $obj->modified([BOOLEAN])
416
417           See "Internals" in Mail::Message::Body
418
419       $obj->moveLocation([DISTANCE])
420
421           See "Internals" in Mail::Message::Body
422
423       $obj->read(PARSER, HEAD, BODYTYPE [,CHARS [,LINES]])
424
425           See "Internals" in Mail::Message::Body
426
427       Error handling
428
429       $obj->AUTOLOAD
430
431           See "Error handling" in Mail::Message::Body
432
433       $obj->addReport(OBJECT)
434
435           See "Error handling" in Mail::Reporter
436
437       $obj->defaultTrace([LEVEL]⎪[LOGLEVEL, TRACELEVEL]⎪[LEVEL, CALLBACK])
438
439       Mail::Message::Body::Multipart->defaultTrace([LEVEL]⎪[LOGLEVEL,
440       TRACELEVEL]⎪[LEVEL, CALLBACK])
441
442           See "Error handling" in Mail::Reporter
443
444       $obj->errors
445
446           See "Error handling" in Mail::Reporter
447
448       $obj->log([LEVEL [,STRINGS]])
449
450       Mail::Message::Body::Multipart->log([LEVEL [,STRINGS]])
451
452           See "Error handling" in Mail::Reporter
453
454       $obj->logPriority(LEVEL)
455
456       Mail::Message::Body::Multipart->logPriority(LEVEL)
457
458           See "Error handling" in Mail::Reporter
459
460       $obj->logSettings
461
462           See "Error handling" in Mail::Reporter
463
464       $obj->notImplemented
465
466           See "Error handling" in Mail::Reporter
467
468       $obj->report([LEVEL])
469
470           See "Error handling" in Mail::Reporter
471
472       $obj->reportAll([LEVEL])
473
474           See "Error handling" in Mail::Reporter
475
476       $obj->trace([LEVEL])
477
478           See "Error handling" in Mail::Reporter
479
480       $obj->warnings
481
482           See "Error handling" in Mail::Reporter
483
484       Cleanup
485
486       $obj->DESTROY
487
488           See "Cleanup" in Mail::Reporter
489
490       $obj->inGlobalDestruction
491
492           See "Cleanup" in Mail::Reporter
493

DETAILS

DIAGNOSTICS

496       Error: Data not convertible to a message (type is $type)
497
498       An object which is not coercable into a Mail::Message::Part object was
499       passed to the initiation.  The data is ignored.
500
501       Warning: No decoder defined for transfer encoding $name.
502
503       The data (message body) is encoded in a way which is not currently
504       understood, therefore no decoding (or recoding) can take place.
505
506       Warning: No encoder defined for transfer encoding $name.
507
508       The data (message body) has been decoded, but the required encoding is
509       unknown.  The decoded data is returned.
510
511       Error: Package $package does not implement $method.
512
513       Fatal error: the specific package (or one of its superclasses) does not
514       implement this method where it should. This message means that some
515       other related classes do implement this method however the class at
516       hand does not.  Probably you should investigate this and probably
517       inform the author of the package.
518
519       Error: Unknown criterium $what to select parts.
520
521       Valid choices fdr part selections are "ALL", "ACTIVE", "DELETED",
522       "RECURSE" or a code reference.  However, some other argument was
523       passed.
524
525       Error: You cannot use foreachLine on a multipart
526
527       foreachLine() should be used on decoded message bodies only, because it
528       would attempt to modify part-headers and separators as well, which is
529       clearly not acceptible.
530

LICENSE

536       Copyrights 2001-2007 by Mark Overmeer.For other contributors see
537       ChangeLog.
538
539       This program is free software; you can redistribute it and/or modify it
540       under the same terms as Perl itself.  See
541       http://www.perl.com/perl/misc/Artistic.html
542
543
544
545perl v5.8.8                       2007-03-25 Mail::Message::Body::Multipart(3)