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
29       Extends "DESCRIPTION" in Mail::Message::Body.
30

OVERLOADED

32       Extends "OVERLOADED" in Mail::Message::Body.
33
34       overload: ""
35           Inherited, see "OVERLOADED" in Mail::Message::Body
36
37       overload: '==' and '!='
38           Inherited, see "OVERLOADED" in Mail::Message::Body
39
40       overload: @{}
41           Inherited, see "OVERLOADED" in Mail::Message::Body
42
43       overload: bool
44           Inherited, see "OVERLOADED" in Mail::Message::Body
45

METHODS

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

DETAILS

422       Extends "DETAILS" in Mail::Message::Body.
423

DIAGNOSTICS

425       Warning: Charset $name is not known
426           The encoding or decoding of a message body encounters a character
427           set which is not understood by Perl's Encode module.
428
429       Error: Data not convertible to a message (type is $type)
430           An object which is not coercable into a Mail::Message::Part object
431           was passed to the initiation.  The data is ignored.
432
433       Warning: No decoder defined for transfer encoding $name.
434           The data (message body) is encoded in a way which is not currently
435           understood, therefore no decoding (or recoding) can take place.
436
437       Warning: No encoder defined for transfer encoding $name.
438           The data (message body) has been decoded, but the required encoding
439           is unknown.  The decoded data is returned.
440
441       Error: Package $package does not implement $method.
442           Fatal error: the specific package (or one of its superclasses) does
443           not implement this method where it should. This message means that
444           some other related classes do implement this method however the
445           class at hand does not.  Probably you should investigate this and
446           probably inform the author of the package.
447
448       Error: Unknown criterium $what to select parts.
449           Valid choices fdr part selections are "ALL", "ACTIVE", "DELETED",
450           "RECURSE" or a code reference.  However, some other argument was
451           passed.
452
453       Warning: Unknown line terminator $eol ignored
454       Error: You cannot use foreachLine on a multipart
455           foreachLine() should be used on decoded message bodies only,
456           because it would attempt to modify part-headers and separators as
457           well, which is clearly not acceptable.
458

LICENSE

464       Copyrights 2001-2022 by [Mark Overmeer <markov@cpan.org>]. For other
465       contributors see ChangeLog.
466
467       This program is free software; you can redistribute it and/or modify it
468       under the same terms as Perl itself.  See http://dev.perl.org/licenses/
469
470
471
472perl v5.34.0                      2022-03-01 Mail::Message::Body::Multipart(3)