1Mail::Message::Body::MuUlsteirpaCrotn(t3r)ibuted Perl DoMcauimle:n:tMaetsisoange::Body::Multipart(3)
2
3
4
6 Mail::Message::Body::Multipart - body of a message with attachments
7
9 Mail::Message::Body::Multipart
10 is a Mail::Message::Body
11 is a Mail::Reporter
12
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
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
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
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
422 Extends "DETAILS" in Mail::Message::Body.
423
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
460 This module is part of Mail-Message distribution version 3.008, built
461 on February 11, 2019. Website: http://perl.overmeer.net/CPAN/
462
464 Copyrights 2001-2019 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.30.0 2019-07-26 Mail::Message::Body::Multipart(3)