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
30 overload: ""
31 See "OVERLOADED" in Mail::Message::Body
32
33 overload: '==' and '!='
34 See "OVERLOADED" in Mail::Message::Body
35
36 overload: @{}
37 See "OVERLOADED" in Mail::Message::Body
38
39 overload: bool
40 See "OVERLOADED" in Mail::Message::Body
41
43 Constructors
44 $obj->clone
45 See "Constructors" in Mail::Message::Body
46
47 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
68 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
75 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
85 Provide a BODY object or a STRING which will automatically
86 translated into a "text/plain" body.
87
88 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
98 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
102 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
108 Provide a BODY object or a STRING which will automatically
109 translated into a text/plain body.
110
111 trace => LEVEL
112 transfer_encoding => STRING|FIELD
113
114 example:
115
116 my $intro = Mail::Message::Body->new(data => ['part one']);
117 my $pgp = Mail::Message::Body->new(data => ['part three']);
118
119 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
125 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
133 $obj->check
134 See "Constructing a body" in Mail::Message::Body::Encode
135
136 $obj->concatenate(COMPONENTS)
137 See "Constructing a body" in Mail::Message::Body::Construct
138
139 $obj->decoded(OPTIONS)
140 See "Constructing a body" in Mail::Message::Body
141
142 $obj->encode(OPTIONS)
143 See "Constructing a body" in Mail::Message::Body::Encode
144
145 $obj->encoded
146 See "Constructing a body" in Mail::Message::Body::Encode
147
148 $obj->eol(['CR'|'LF'|'CRLF'|'NATIVE'])
149 See "Constructing a body" in Mail::Message::Body
150
151 $obj->foreachComponent(CODE)
152 Execute the CODE for each component of the message: the preamble,
153 the epilogue, and each of the parts.
154
155 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
162 example:
163
164 my $checked = $multi->foreachComponent(sub {$_[1]->check});
165
166 $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
171 $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
178 -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
183 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
189 The body
190 $obj->isDelayed
191 See "The body" in Mail::Message::Body
192
193 $obj->isMultipart
194 See "The body" in Mail::Message::Body
195
196 $obj->isNested
197 See "The body" in Mail::Message::Body
198
199 $obj->message([MESSAGE])
200 See "The body" in Mail::Message::Body
201
202 About the payload
203 $obj->charset
204 See "About the payload" in Mail::Message::Body
205
206 $obj->checked([BOOLEAN])
207 See "About the payload" in Mail::Message::Body
208
209 $obj->description([STRING|FIELD])
210 See "About the payload" in Mail::Message::Body
211
212 $obj->disposition([STRING|FIELD])
213 See "About the payload" in Mail::Message::Body
214
215 $obj->dispositionFilename([DIRECTORY])
216 See "About the payload" in Mail::Message::Body::Encode
217
218 $obj->isBinary
219 See "About the payload" in Mail::Message::Body::Encode
220
221 $obj->isText
222 See "About the payload" in Mail::Message::Body::Encode
223
224 $obj->mimeType
225 See "About the payload" in Mail::Message::Body
226
227 $obj->nrLines
228 See "About the payload" in Mail::Message::Body
229
230 $obj->size
231 See "About the payload" in Mail::Message::Body
232
233 $obj->transferEncoding([STRING|FIELD])
234 See "About the payload" in Mail::Message::Body
235
236 $obj->type([STRING|FIELD])
237 See "About the payload" in Mail::Message::Body
238
239 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
245 $obj->endsOnNewline
246 See "Access to the payload" in Mail::Message::Body
247
248 $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
254 $obj->file
255 See "Access to the payload" in Mail::Message::Body
256
257 $obj->lines
258 See "Access to the payload" in Mail::Message::Body
259
260 $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
265 example:
266
267 $message->body->part(2)->print;
268 $body->part(1)->delete;
269
270 $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
276 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
280 example:
281
282 print "Number of attachments: ",
283 scalar $message->body->parts('ACTIVE');
284
285 foreach my $part ($message->body->parts) {
286 print "Type: ", $part->get('Content-Type');
287 }
288
289 $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
294 $obj->print([FILEHANDLE])
295 See "Access to the payload" in Mail::Message::Body
296
297 $obj->printEscapedFrom(FILEHANDLE)
298 See "Access to the payload" in Mail::Message::Body
299
300 $obj->string
301 See "Access to the payload" in Mail::Message::Body
302
303 $obj->stripTrailingNewline
304 See "Access to the payload" in Mail::Message::Body
305
306 $obj->write(OPTIONS)
307 See "Access to the payload" in Mail::Message::Body
308
309 Internals
310 $obj->addTransferEncHandler(NAME, CLASS|OBJECT)
311 Mail::Message::Body::Multipart->addTransferEncHandler(NAME,
312 CLASS|OBJECT)
313
314 See "Internals" in Mail::Message::Body::Encode
315
316 $obj->contentInfoFrom(HEAD)
317 See "Internals" in Mail::Message::Body
318
319 $obj->contentInfoTo(HEAD)
320 See "Internals" in Mail::Message::Body
321
322 $obj->fileLocation([BEGIN,END])
323 See "Internals" in Mail::Message::Body
324
325 $obj->getTransferEncHandler(TYPE)
326 See "Internals" in Mail::Message::Body::Encode
327
328 $obj->isModified
329 See "Internals" in Mail::Message::Body
330
331 $obj->load
332 See "Internals" in Mail::Message::Body
333
334 $obj->modified([BOOLEAN])
335 See "Internals" in Mail::Message::Body
336
337 $obj->moveLocation([DISTANCE])
338 See "Internals" in Mail::Message::Body
339
340 $obj->read(PARSER, HEAD, BODYTYPE [,CHARS [,LINES]])
341 See "Internals" in Mail::Message::Body
342
343 Error handling
344 $obj->AUTOLOAD
345 See "Error handling" in Mail::Message::Body
346
347 $obj->addReport(OBJECT)
348 See "Error handling" in Mail::Reporter
349
350 $obj->defaultTrace([LEVEL]|[LOGLEVEL, TRACELEVEL]|[LEVEL, CALLBACK])
351 Mail::Message::Body::Multipart->defaultTrace([LEVEL]|[LOGLEVEL,
352 TRACELEVEL]|[LEVEL, CALLBACK])
353
354 See "Error handling" in Mail::Reporter
355
356 $obj->errors
357 See "Error handling" in Mail::Reporter
358
359 $obj->log([LEVEL [,STRINGS]])
360 Mail::Message::Body::Multipart->log([LEVEL [,STRINGS]])
361
362 See "Error handling" in Mail::Reporter
363
364 $obj->logPriority(LEVEL)
365 Mail::Message::Body::Multipart->logPriority(LEVEL)
366
367 See "Error handling" in Mail::Reporter
368
369 $obj->logSettings
370 See "Error handling" in Mail::Reporter
371
372 $obj->notImplemented
373 See "Error handling" in Mail::Reporter
374
375 $obj->report([LEVEL])
376 See "Error handling" in Mail::Reporter
377
378 $obj->reportAll([LEVEL])
379 See "Error handling" in Mail::Reporter
380
381 $obj->trace([LEVEL])
382 See "Error handling" in Mail::Reporter
383
384 $obj->warnings
385 See "Error handling" in Mail::Reporter
386
387 Cleanup
388 $obj->DESTROY
389 See "Cleanup" in Mail::Reporter
390
391 $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
399 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
403 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
407 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
411 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
418 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
423 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
437 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
440
441
442
443perl v5.12.3 2011-01-26 Mail::Message::Body::Multipart(3)