1Mail::Message::Body::MuUlsteirpaCrotn(t3r)ibuted Perl DoMcauimle:n:tMaetsisoange::Body::Multipart(3)
2
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 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
30 overload: ""
31 See "OVERLOADED" in Mail::Message::Body
32 overload: '==' and '!='
34 See "OVERLOADED" in Mail::Message::Body
35 overload: @{}
37 See "OVERLOADED" in Mail::Message::Body
38 overload: bool
40 See "OVERLOADED" in Mail::Message::Body
41
43 Constructors
44 $obj->clone
45 See "Constructors" in Mail::Message::Body
46 Mail::Message::Body::Multipart->new(OPTIONS)
48 -Option --Defined in --Default
49 based_on Mail::Message::Body undef
50 boundary undef
51 charset Mail::Message::Body 'PERL' or <undef>
52 checked Mail::Message::Body <false>
53 data Mail::Message::Body undef
54 description Mail::Message::Body undef
55 disposition Mail::Message::Body undef
56 eol Mail::Message::Body 'NATIVE'
57 epilogue ''
58 file Mail::Message::Body undef
59 log Mail::Reporter 'WARNINGS'
60 message Mail::Message::Body undef
61 mime_type Mail::Message::Body 'multipart/mixed'
62 modified Mail::Message::Body <false>
63 parts undef
64 preamble undef
65 trace Mail::Reporter 'WARNINGS'
66 transfer_encoding Mail::Message::Body 'none'
67 based_on => BODY
69 boundary => STRING
70 Separator to be used between parts of the message. This
71 separator must be unique in case the message contains nested
72 multiparts (which are not unusual). If "undef", a nice unique
73 boundary will be generated.
74 charset => CHARSET|'PERL'
76 checked => BOOLEAN
77 data => ARRAY-OF-LINES | STRING
78 description => STRING|FIELD
79 disposition => STRING|FIELD
80 eol => 'CR'|'LF'|'CRLF'|'NATIVE'
81 epilogue => BODY|STRING
82 The text which is included in the main body after the final
83 boundary. This is usually empty, and has no meaning.
84 Provide a BODY object or a STRING which will automatically
86 translated into a "text/plain" body.
87 file => FILENAME|FILEHANDLE|IOHANDLE
89 log => LEVEL
90 message => MESSAGE
91 mime_type => STRING|FIELD|MIME
92 modified => BOOLEAN
93 parts => ARRAY-OF-(MESSAGES|BODIES)
94 Specifies an initial list of parts in this body. These may be
95 full MESSAGES, or BODIES which transformed into messages before
96 use. Each message is coerced into a Mail::Message::Part object.
97 MIME::Entity and Mail::Internet objects are acceptable in the
99 list, because they are coercible into Mail::Message::Part's.
100 Values of "undef" will be skipped silently.
101 preamble => BODY|STRING
103 The text which is included in the body before the first part. It
104 is common use to include a text to warn the user that the message
105 is a multipart. However, this was useful in earlier days: most
106 mail agents are very capable in warning the user themselves.
107 Provide a BODY object or a STRING which will automatically
109 translated into a text/plain body.
110 trace => LEVEL
112 transfer_encoding => STRING|FIELD
113 example:
115 my $intro = Mail::Message::Body->new(data => ['part one']);
117 my $pgp = Mail::Message::Body->new(data => ['part three']);
118 my $body = Mail::Message::Body::Multipart->new
120 ( boundary => time . '--it-s-mine'
121 , preamble => "This is a multi-part message in MIME format.\n\n"
122 , parts => [ $intro, $folder->message(3)->decoded, $pgp ]
123 );
124 Constructing a body
126 $obj->attach(MESSAGES|BODIES)
127 Attach a list of MESSAGES to this multipart. A new body is
128 returned. When you specify BODIES, they will first be translated
129 into real messages. MIME::Entity and Mail::Internet objects may be
130 specified too. In any case, the parts will be coerced into
131 Mail::Message::Part's.
132 $obj->check
134 See "Constructing a body" in Mail::Message::Body::Encode
135 $obj->concatenate(COMPONENTS)
137 See "Constructing a body" in Mail::Message::Body::Construct
138 $obj->decoded(OPTIONS)
140 See "Constructing a body" in Mail::Message::Body
141 $obj->encode(OPTIONS)
143 See "Constructing a body" in Mail::Message::Body::Encode
144 $obj->encoded
146 See "Constructing a body" in Mail::Message::Body::Encode
147 $obj->eol(['CR'|'LF'|'CRLF'|'NATIVE'])
149 See "Constructing a body" in Mail::Message::Body
150 $obj->foreachComponent(CODE)
152 Execute the CODE for each component of the message: the preamble,
153 the epilogue, and each of the parts.
154 Each component is a body and is passed as second argument to the
156 CODE. The first argument is a reference to this multi-parted body.
157 The CODE returns a body object. When any of the returned bodies
158 differs from the body which was passed, then a new multi-part body
159 will be returned. Reference to the not-changed bodies and the
160 changed bodies will be included in that new multi-part.
161 example:
163 my $checked = $multi->foreachComponent(sub {$_[1]->check});
165 $obj->foreachLine((CODE))
167 It is NOT possible to call some code for each line of a multipart,
168 because that would not only inflict damage to the body of each
169 message part, but also to the headers and the part separators.
170 $obj->stripSignature(OPTIONS)
172 Removes all parts which contains data usually defined as being
173 signature. The MIME::Type module provides this knowledge. A new
174 multipart is returned, containing the remaining parts. No OPTIONS
175 are defined yet, although some may be specified, because this
176 method overrules the "stripSignature" method for normal bodies.
177 -Option --Defined in --Default
179 max_lines Mail::Message::Body::Construct 10
180 pattern Mail::Message::Body::Construct qr/^--\s?$/
181 result_type Mail::Message::Body::Construct <same as current>
182 max_lines => INTEGER|undef
184 pattern => REGEX|STRING|CODE
185 result_type => CLASS
186 $obj->unify(BODY)
187 See "Constructing a body" in Mail::Message::Body::Encode
188 The body
190 $obj->isDelayed
191 See "The body" in Mail::Message::Body
192 $obj->isMultipart
194 See "The body" in Mail::Message::Body
195 $obj->isNested
197 See "The body" in Mail::Message::Body
198 $obj->message([MESSAGE])
200 See "The body" in Mail::Message::Body
201 About the payload
203 $obj->charset
204 See "About the payload" in Mail::Message::Body
205 $obj->checked([BOOLEAN])
207 See "About the payload" in Mail::Message::Body
208 $obj->description([STRING|FIELD])
210 See "About the payload" in Mail::Message::Body
211 $obj->disposition([STRING|FIELD])
213 See "About the payload" in Mail::Message::Body
214 $obj->dispositionFilename([DIRECTORY])
216 See "About the payload" in Mail::Message::Body::Encode
217 $obj->isBinary
219 See "About the payload" in Mail::Message::Body::Encode
220 $obj->isText
222 See "About the payload" in Mail::Message::Body::Encode
223 $obj->mimeType
225 See "About the payload" in Mail::Message::Body
226 $obj->nrLines
228 See "About the payload" in Mail::Message::Body
229 $obj->size
231 See "About the payload" in Mail::Message::Body
232 $obj->transferEncoding([STRING|FIELD])
234 See "About the payload" in Mail::Message::Body
235 $obj->type([STRING|FIELD])
237 See "About the payload" in Mail::Message::Body
238 Access to the payload
240 $obj->boundary([STRING])
241 Returns the boundary which is used to separate the parts in this
242 body. If none was read from file, then one will be assigned. With
243 STRING you explicitly set the boundary to be used.
244 $obj->endsOnNewline
246 See "Access to the payload" in Mail::Message::Body
247 $obj->epilogue
249 Returns the epilogue; the text after the last message part (after
250 the last real attachment). The epilogue is stored in a BODY
251 object, and its encoding is taken from the general multipart
252 header.
253 $obj->file
255 See "Access to the payload" in Mail::Message::Body
256 $obj->lines
258 See "Access to the payload" in Mail::Message::Body
259 $obj->part(INDEX)
261 Returns only the part with the specified INDEX. You may use a
262 negative value here, which counts from the back in the list. Parts
263 which are flagged to be deleted are included in the count.
264 example:
266 $message->body->part(2)->print;
268 $body->part(1)->delete;
269 $obj->parts(['ALL'|'ACTIVE'|'DELETED'|'RECURSE'|FILTER])
271 Return all parts by default, or when ALL is specified. "ACTIVE"
272 returns the parts which are not flagged for deletion, as opposite
273 to "DELETED". "RECURSE" descents into all nested multiparts to
274 collect all parts.
275 You may also specify a code reference which is called for each
277 nested part. The first argument will be the message part. When
278 the code returns true, the part is incorporated in the return list.
279 example:
281 print "Number of attachments: ",
283 scalar $message->body->parts('ACTIVE');
284 foreach my $part ($message->body->parts) {
286 print "Type: ", $part->get('Content-Type');
287 }
288 $obj->preamble
290 Returns the preamble; the text before the first message part
291 (before the first real attachment). The preamble is stored in a
292 BODY object, and its encoding is taken from the multipart header.
293 $obj->print([FILEHANDLE])
295 See "Access to the payload" in Mail::Message::Body
296 $obj->printEscapedFrom(FILEHANDLE)
298 See "Access to the payload" in Mail::Message::Body
299 $obj->string
301 See "Access to the payload" in Mail::Message::Body
302 $obj->stripTrailingNewline
304 See "Access to the payload" in Mail::Message::Body
305 $obj->write(OPTIONS)
307 See "Access to the payload" in Mail::Message::Body
308 Internals
310 $obj->addTransferEncHandler(NAME, CLASS|OBJECT)
311 Mail::Message::Body::Multipart->addTransferEncHandler(NAME,
312 CLASS|OBJECT)
313 See "Internals" in Mail::Message::Body::Encode
315 $obj->contentInfoFrom(HEAD)
317 See "Internals" in Mail::Message::Body
318 $obj->contentInfoTo(HEAD)
320 See "Internals" in Mail::Message::Body
321 $obj->fileLocation([BEGIN,END])
323 See "Internals" in Mail::Message::Body
324 $obj->getTransferEncHandler(TYPE)
326 See "Internals" in Mail::Message::Body::Encode
327 $obj->isModified
329 See "Internals" in Mail::Message::Body
330 $obj->load
332 See "Internals" in Mail::Message::Body
333 $obj->modified([BOOLEAN])
335 See "Internals" in Mail::Message::Body
336 $obj->moveLocation([DISTANCE])
338 See "Internals" in Mail::Message::Body
339 $obj->read(PARSER, HEAD, BODYTYPE [,CHARS [,LINES]])
341 See "Internals" in Mail::Message::Body
342 Error handling
344 $obj->AUTOLOAD
345 See "Error handling" in Mail::Message::Body
346 $obj->addReport(OBJECT)
348 See "Error handling" in Mail::Reporter
349 $obj->defaultTrace([LEVEL]|[LOGLEVEL, TRACELEVEL]|[LEVEL, CALLBACK])
351 Mail::Message::Body::Multipart->defaultTrace([LEVEL]|[LOGLEVEL,
352 TRACELEVEL]|[LEVEL, CALLBACK])
353 See "Error handling" in Mail::Reporter
355 $obj->errors
357 See "Error handling" in Mail::Reporter
358 $obj->log([LEVEL [,STRINGS]])
360 Mail::Message::Body::Multipart->log([LEVEL [,STRINGS]])
361 See "Error handling" in Mail::Reporter
363 $obj->logPriority(LEVEL)
365 Mail::Message::Body::Multipart->logPriority(LEVEL)
366 See "Error handling" in Mail::Reporter
368 $obj->logSettings
370 See "Error handling" in Mail::Reporter
371 $obj->notImplemented
373 See "Error handling" in Mail::Reporter
374 $obj->report([LEVEL])
376 See "Error handling" in Mail::Reporter
377 $obj->reportAll([LEVEL])
379 See "Error handling" in Mail::Reporter
380 $obj->trace([LEVEL])
382 See "Error handling" in Mail::Reporter
383 $obj->warnings
385 See "Error handling" in Mail::Reporter
386 Cleanup
388 $obj->DESTROY
389 See "Cleanup" in Mail::Reporter
390 $obj->inGlobalDestruction
392 See "Cleanup" in Mail::Reporter
393
395 Warning: Charset $name is not known
396 The encoding or decoding of a message body encounters a character
397 set which is not understood by Perl's Encode module.
398 Error: Data not convertible to a message (type is $type)
400 An object which is not coercable into a Mail::Message::Part object
401 was passed to the initiation. The data is ignored.
402 Warning: No decoder defined for transfer encoding $name.
404 The data (message body) is encoded in a way which is not currently
405 understood, therefore no decoding (or recoding) can take place.
406 Warning: No encoder defined for transfer encoding $name.
408 The data (message body) has been decoded, but the required encoding
409 is unknown. The decoded data is returned.
410 Error: Package $package does not implement $method.
412 Fatal error: the specific package (or one of its superclasses) does
413 not implement this method where it should. This message means that
414 some other related classes do implement this method however the
415 class at hand does not. Probably you should investigate this and
416 probably inform the author of the package.
417 Error: Unknown criterium $what to select parts.
419 Valid choices fdr part selections are "ALL", "ACTIVE", "DELETED",
420 "RECURSE" or a code reference. However, some other argument was
421 passed.
422 Warning: Unknown line terminator $eol ignored
424 Error: You cannot use foreachLine on a multipart
425 foreachLine() should be used on decoded message bodies only,
426 because it would attempt to modify part-headers and separators as
427 well, which is clearly not acceptible.
428
430 This module is part of Mail-Box distribution version 2.097, built on
431 January 26, 2011. Website: http://perl.overmeer.net/mailbox/
432
434 Copyrights 2001-2011 by Mark Overmeer. For other contributors see
435 ChangeLog.
436 This program is free software; you can redistribute it and/or modify it
438 under the same terms as Perl itself. See
439 http://www.perl.com/perl/misc/Artistic.html
440perl v5.12.3 2011-01-26 Mail::Message::Body::Multipart(3)