1=encoding utf8 2 3=head1 NAME 4 5Mail::Message::Body::Multipart - body of a message with attachments 6 7=head1 INHERITANCE 8 9 Mail::Message::Body::Multipart 10 is a Mail::Message::Body 11 is a Mail::Reporter 12 13=head1 SYNOPSIS 14 15 See Mail::Message::Body 16 17 if($body->isMultipart) { 18 my @attachments = $body->parts; 19 my $attachment3 = $body->part(2); 20 my $before = $body->preamble; 21 my $after = $body->epilogue; 22 $body->part(1)->delete; 23 } 24 25=head1 DESCRIPTION 26 27The body (content) of a message can be stored in various ways. In this 28manual-page you find the description of extra functionality you have 29when a message contains attachments (parts). 30 31Extends L<"DESCRIPTION" in Mail::Message::Body|Mail::Message::Body/"DESCRIPTION">. 32 33=head1 OVERLOADED 34 35Extends L<"OVERLOADED" in Mail::Message::Body|Mail::Message::Body/"OVERLOADED">. 36 37=over 4 38 39=item overload: B<""> 40 41Inherited, see L<Mail::Message::Body/"OVERLOADED"> 42 43=item overload: B<'==' and '!='> 44 45Inherited, see L<Mail::Message::Body/"OVERLOADED"> 46 47=item overload: B<@{}> 48 49Inherited, see L<Mail::Message::Body/"OVERLOADED"> 50 51=item overload: B<bool> 52 53Inherited, see L<Mail::Message::Body/"OVERLOADED"> 54 55=back 56 57=head1 METHODS 58 59Extends L<"METHODS" in Mail::Message::Body|Mail::Message::Body/"METHODS">. 60 61=head2 Constructors 62 63Extends L<"Constructors" in Mail::Message::Body|Mail::Message::Body/"Constructors">. 64 65=over 4 66 67=item $obj-E<gt>B<clone>() 68 69Inherited, see L<Mail::Message::Body/"Constructors"> 70 71=item Mail::Message::Body::Multipart-E<gt>B<new>(%options) 72 73 -Option --Defined in --Default 74 based_on Mail::Message::Body undef 75 boundary undef 76 charset Mail::Message::Body 'PERL' or <undef> 77 checked Mail::Message::Body <false> 78 content_id Mail::Message::Body undef 79 data Mail::Message::Body undef 80 description Mail::Message::Body undef 81 disposition Mail::Message::Body undef 82 eol Mail::Message::Body 'NATIVE' 83 epilogue '' 84 file Mail::Message::Body undef 85 filename Mail::Message::Body undef 86 log Mail::Reporter 'WARNINGS' 87 message Mail::Message::Body undef 88 mime_type Mail::Message::Body 'multipart/mixed' 89 modified Mail::Message::Body <false> 90 parts undef 91 preamble undef 92 trace Mail::Reporter 'WARNINGS' 93 transfer_encoding Mail::Message::Body 'none' 94 95=over 2 96 97=item based_on => BODY 98 99=item boundary => STRING 100 101Separator to be used between parts of the message. This separator must 102be unique in case the message contains nested multiparts (which are not 103unusual). If C<undef>, a nice unique boundary will be generated. 104 105=item charset => CHARSET|'PERL' 106 107=item checked => BOOLEAN 108 109=item content_id => STRING 110 111=item data => ARRAY-OF-LINES | STRING 112 113=item description => STRING|FIELD 114 115=item disposition => STRING|FIELD 116 117=item eol => 'CR'|'LF'|'CRLF'|'NATIVE' 118 119=item epilogue => BODY|STRING 120 121The text which is included in the main body after the final boundary. This 122is usually empty, and has no meaning. 123 124Provide a BODY object or a STRING which will automatically translated 125into a C<text/plain> body. 126 127=item file => FILENAME|FILEHANDLE|IOHANDLE 128 129=item filename => FILENAME 130 131=item log => LEVEL 132 133=item message => MESSAGE 134 135=item mime_type => STRING|FIELD|MIME 136 137=item modified => BOOLEAN 138 139=item parts => ARRAY-OF-(MESSAGES|BODIES) 140 141Specifies an initial list of parts in this body. These may be full 142MESSAGES, or BODIES which transformed into messages before use. Each 143message is coerced into a L<Mail::Message::Part|Mail::Message::Part> object. 144 145MIME::Entity and L<Mail::Internet|Mail::Internet> objects are acceptable in the 146list, because they are coercible into L<Mail::Message::Part|Mail::Message::Part>'s. Values 147of C<undef> will be skipped silently. 148 149=item preamble => BODY|STRING 150 151The text which is included in the body before the first part. It is 152common use to include a text to warn the user that the message is a 153multipart. However, this was useful in earlier days: most mail 154agents are very capable in warning the user themselves. 155 156Provide a BODY object or a STRING which will automatically translated 157into a text/plain body. 158 159=item trace => LEVEL 160 161=item transfer_encoding => STRING|FIELD 162 163=back 164 165example: 166 167 my $intro = Mail::Message::Body->new(data => ['part one']); 168 my $pgp = Mail::Message::Body->new(data => ['part three']); 169 170 my $body = Mail::Message::Body::Multipart->new 171 ( boundary => time . '--it-s-mine' 172 , preamble => "This is a multi-part message in MIME format.\n\n" 173 , parts => [ $intro, $folder->message(3)->decoded, $pgp ] 174 ); 175 176=back 177 178=head2 Constructing a body 179 180Extends L<"Constructing a body" in Mail::Message::Body|Mail::Message::Body/"Constructing a body">. 181 182=over 4 183 184=item $obj-E<gt>B<attach>($messages|$bodies) 185 186Attach a list of $messages to this multipart. A new body is returned. 187When you specify $bodies, they will first be translated into 188real messages. MIME::Entity and L<Mail::Internet|Mail::Internet> objects may be 189specified too. In any case, the parts will be coerced into 190L<Mail::Message::Part|Mail::Message::Part>'s. 191 192=item $obj-E<gt>B<check>() 193 194Inherited, see L<Mail::Message::Body::Encode/"Constructing a body"> 195 196=item $obj-E<gt>B<concatenate>($components) 197 198Inherited, see L<Mail::Message::Body::Construct/"Constructing a body"> 199 200=item $obj-E<gt>B<decoded>(%options) 201 202Inherited, see L<Mail::Message::Body/"Constructing a body"> 203 204=item $obj-E<gt>B<encode>(%options) 205 206Inherited, see L<Mail::Message::Body::Encode/"Constructing a body"> 207 208=item $obj-E<gt>B<encoded>() 209 210Inherited, see L<Mail::Message::Body::Encode/"Constructing a body"> 211 212=item $obj-E<gt>B<eol>( ['CR'|'LF'|'CRLF'|'NATIVE'] ) 213 214Inherited, see L<Mail::Message::Body/"Constructing a body"> 215 216=item $obj-E<gt>B<foreachComponent>(CODE) 217 218Execute the CODE for each component of the message: the preamble, the 219epilogue, and each of the parts. 220 221Each component is a body and is passed as second argument to the CODE. 222The first argument is a reference to this multi-parted body. The CODE 223returns a body object. When any of the returned bodies differs from 224the body which was passed, then a new multi-part body will be returned. 225Reference to the not-changed bodies and the changed bodies will be 226included in that new multi-part. 227 228example: 229 230 my $checked = $multi->foreachComponent(sub {$_[1]->check}); 231 232=item $obj-E<gt>B<foreachLine>((CODE)) 233 234It is NOT possible to call some code for each line of a multipart, 235because that would not only inflict damage to the body of each 236message part, but also to the headers and the part separators. 237 238=item $obj-E<gt>B<stripSignature>(%options) 239 240Removes all parts which contains data usually defined as being signature. 241The L<MIME::Type|MIME::Type> module provides this knowledge. A new multipart is 242returned, containing the remaining parts. No %options are defined yet, 243although some may be specified, because this method overrules the 244C<stripSignature> method for normal bodies. 245 246 -Option --Defined in --Default 247 max_lines Mail::Message::Body::Construct 10 248 pattern Mail::Message::Body::Construct qr/^--\s?$/ 249 result_type Mail::Message::Body::Construct <same as current> 250 251=over 2 252 253=item max_lines => INTEGER|undef 254 255=item pattern => REGEX|STRING|CODE 256 257=item result_type => CLASS 258 259=back 260 261=item $obj-E<gt>B<unify>($body) 262 263Inherited, see L<Mail::Message::Body::Encode/"Constructing a body"> 264 265=back 266 267=head2 The body 268 269Extends L<"The body" in Mail::Message::Body|Mail::Message::Body/"The body">. 270 271=over 4 272 273=item $obj-E<gt>B<isDelayed>() 274 275Inherited, see L<Mail::Message::Body/"The body"> 276 277=item $obj-E<gt>B<isMultipart>() 278 279Inherited, see L<Mail::Message::Body/"The body"> 280 281=item $obj-E<gt>B<isNested>() 282 283Inherited, see L<Mail::Message::Body/"The body"> 284 285=item $obj-E<gt>B<message>( [$message] ) 286 287Inherited, see L<Mail::Message::Body/"The body"> 288 289=item $obj-E<gt>B<partNumberOf>($part) 290 291Inherited, see L<Mail::Message::Body/"The body"> 292 293=back 294 295=head2 About the payload 296 297Extends L<"About the payload" in Mail::Message::Body|Mail::Message::Body/"About the payload">. 298 299=over 4 300 301=item $obj-E<gt>B<charset>() 302 303Inherited, see L<Mail::Message::Body/"About the payload"> 304 305=item $obj-E<gt>B<checked>( [BOOLEAN] ) 306 307Inherited, see L<Mail::Message::Body/"About the payload"> 308 309=item $obj-E<gt>B<contentId>( [STRING|$field] ) 310 311Inherited, see L<Mail::Message::Body/"About the payload"> 312 313=item $obj-E<gt>B<description>( [STRING|$field] ) 314 315Inherited, see L<Mail::Message::Body/"About the payload"> 316 317=item $obj-E<gt>B<disposition>( [STRING|$field] ) 318 319Inherited, see L<Mail::Message::Body/"About the payload"> 320 321=item $obj-E<gt>B<dispositionFilename>( [$directory] ) 322 323Inherited, see L<Mail::Message::Body::Encode/"About the payload"> 324 325=item $obj-E<gt>B<isBinary>() 326 327Inherited, see L<Mail::Message::Body::Encode/"About the payload"> 328 329=item $obj-E<gt>B<isText>() 330 331Inherited, see L<Mail::Message::Body::Encode/"About the payload"> 332 333=item $obj-E<gt>B<mimeType>() 334 335Inherited, see L<Mail::Message::Body/"About the payload"> 336 337=item $obj-E<gt>B<nrLines>() 338 339Inherited, see L<Mail::Message::Body/"About the payload"> 340 341=item $obj-E<gt>B<size>() 342 343Inherited, see L<Mail::Message::Body/"About the payload"> 344 345=item $obj-E<gt>B<transferEncoding>( [STRING|$field] ) 346 347Inherited, see L<Mail::Message::Body/"About the payload"> 348 349=item $obj-E<gt>B<type>( [STRING|$field] ) 350 351Inherited, see L<Mail::Message::Body/"About the payload"> 352 353=back 354 355=head2 Access to the payload 356 357Extends L<"Access to the payload" in Mail::Message::Body|Mail::Message::Body/"Access to the payload">. 358 359=over 4 360 361=item $obj-E<gt>B<boundary>( [STRING] ) 362 363Returns the boundary which is used to separate the parts in this 364body. If none was read from file, then one will be assigned. With 365STRING you explicitly set the boundary to be used. 366 367=item $obj-E<gt>B<endsOnNewline>() 368 369Inherited, see L<Mail::Message::Body/"Access to the payload"> 370 371=item $obj-E<gt>B<epilogue>() 372 373Returns the epilogue; the text after the last message part (after the 374last real attachment). 375The epilogue is stored in a BODY object, and its encoding is taken 376from the general multipart header. 377 378=item $obj-E<gt>B<file>() 379 380Inherited, see L<Mail::Message::Body/"Access to the payload"> 381 382=item $obj-E<gt>B<lines>() 383 384Inherited, see L<Mail::Message::Body/"Access to the payload"> 385 386=item $obj-E<gt>B<part>($index) 387 388Returns only the part with the specified $index. You may use a negative 389value here, which counts from the back in the list. Parts which are 390flagged to be deleted are included in the count. 391 392example: 393 394 $message->body->part(2)->print; 395 $body->part(1)->delete; 396 397=item $obj-E<gt>B<parts>( [<'ALL'|'ACTIVE'|'DELETED'|'RECURSE'|$filter>] ) 398 399Return all parts by default, or when ALL is specified. C<ACTIVE> returns 400the parts which are not flagged for deletion, as opposite to C<DELETED>. 401C<RECURSE> descents into all nested multiparts to collect all parts. 402 403You may also specify a code reference which is called for each nested 404part. The first argument will be the message part. When the code 405returns true, the part is incorporated in the return list. 406 407example: 408 409 print "Number of attachments: ", 410 scalar $message->body->parts('ACTIVE'); 411 412 foreach my $part ($message->body->parts) { 413 print "Type: ", $part->get('Content-Type'); 414 } 415 416=item $obj-E<gt>B<preamble>() 417 418Returns the preamble; the text before the first message part (before the 419first real attachment). 420The preamble is stored in a BODY object, and its encoding is taken 421from the multipart header. 422 423=item $obj-E<gt>B<print>( [$fh] ) 424 425Inherited, see L<Mail::Message::Body/"Access to the payload"> 426 427=item $obj-E<gt>B<printEscapedFrom>($fh) 428 429Inherited, see L<Mail::Message::Body/"Access to the payload"> 430 431=item $obj-E<gt>B<string>() 432 433Inherited, see L<Mail::Message::Body/"Access to the payload"> 434 435=item $obj-E<gt>B<stripTrailingNewline>() 436 437Inherited, see L<Mail::Message::Body/"Access to the payload"> 438 439=item $obj-E<gt>B<write>(%options) 440 441Inherited, see L<Mail::Message::Body/"Access to the payload"> 442 443=back 444 445=head2 Internals 446 447Extends L<"Internals" in Mail::Message::Body|Mail::Message::Body/"Internals">. 448 449=over 4 450 451=item $obj-E<gt>B<addTransferEncHandler>( $name, <$class|$object> ) 452 453=item Mail::Message::Body::Multipart-E<gt>B<addTransferEncHandler>( $name, <$class|$object> ) 454 455Inherited, see L<Mail::Message::Body::Encode/"Internals"> 456 457=item $obj-E<gt>B<contentInfoFrom>($head) 458 459Inherited, see L<Mail::Message::Body/"Internals"> 460 461=item $obj-E<gt>B<contentInfoTo>($head) 462 463Inherited, see L<Mail::Message::Body/"Internals"> 464 465=item $obj-E<gt>B<fileLocation>( [$begin, $end] ) 466 467Inherited, see L<Mail::Message::Body/"Internals"> 468 469=item $obj-E<gt>B<getTransferEncHandler>($type) 470 471Inherited, see L<Mail::Message::Body::Encode/"Internals"> 472 473=item $obj-E<gt>B<isModified>() 474 475Inherited, see L<Mail::Message::Body/"Internals"> 476 477=item $obj-E<gt>B<load>() 478 479Inherited, see L<Mail::Message::Body/"Internals"> 480 481=item $obj-E<gt>B<modified>( [BOOLEAN] ) 482 483Inherited, see L<Mail::Message::Body/"Internals"> 484 485=item $obj-E<gt>B<moveLocation>( [$distance] ) 486 487Inherited, see L<Mail::Message::Body/"Internals"> 488 489=item $obj-E<gt>B<read>( $parser, $head, $bodytype, [$chars, [$lines]] ) 490 491Inherited, see L<Mail::Message::Body/"Internals"> 492 493=back 494 495=head2 Error handling 496 497Extends L<"Error handling" in Mail::Message::Body|Mail::Message::Body/"Error handling">. 498 499=over 4 500 501=item $obj-E<gt>B<AUTOLOAD>() 502 503Inherited, see L<Mail::Message::Body/"Error handling"> 504 505=item $obj-E<gt>B<addReport>($object) 506 507Inherited, see L<Mail::Reporter/"Error handling"> 508 509=item $obj-E<gt>B<defaultTrace>( [$level]|[$loglevel, $tracelevel]|[$level, $callback] ) 510 511=item Mail::Message::Body::Multipart-E<gt>B<defaultTrace>( [$level]|[$loglevel, $tracelevel]|[$level, $callback] ) 512 513Inherited, see L<Mail::Reporter/"Error handling"> 514 515=item $obj-E<gt>B<errors>() 516 517Inherited, see L<Mail::Reporter/"Error handling"> 518 519=item $obj-E<gt>B<log>( [$level, [$strings]] ) 520 521=item Mail::Message::Body::Multipart-E<gt>B<log>( [$level, [$strings]] ) 522 523Inherited, see L<Mail::Reporter/"Error handling"> 524 525=item $obj-E<gt>B<logPriority>($level) 526 527=item Mail::Message::Body::Multipart-E<gt>B<logPriority>($level) 528 529Inherited, see L<Mail::Reporter/"Error handling"> 530 531=item $obj-E<gt>B<logSettings>() 532 533Inherited, see L<Mail::Reporter/"Error handling"> 534 535=item $obj-E<gt>B<notImplemented>() 536 537Inherited, see L<Mail::Reporter/"Error handling"> 538 539=item $obj-E<gt>B<report>( [$level] ) 540 541Inherited, see L<Mail::Reporter/"Error handling"> 542 543=item $obj-E<gt>B<reportAll>( [$level] ) 544 545Inherited, see L<Mail::Reporter/"Error handling"> 546 547=item $obj-E<gt>B<trace>( [$level] ) 548 549Inherited, see L<Mail::Reporter/"Error handling"> 550 551=item $obj-E<gt>B<warnings>() 552 553Inherited, see L<Mail::Reporter/"Error handling"> 554 555=back 556 557=head2 Cleanup 558 559Extends L<"Cleanup" in Mail::Message::Body|Mail::Message::Body/"Cleanup">. 560 561=over 4 562 563=item $obj-E<gt>B<DESTROY>() 564 565Inherited, see L<Mail::Reporter/"Cleanup"> 566 567=back 568 569=head1 DETAILS 570 571Extends L<"DETAILS" in Mail::Message::Body|Mail::Message::Body/"DETAILS">. 572 573=head1 DIAGNOSTICS 574 575=over 4 576 577=item Warning: Charset $name is not known 578 579The encoding or decoding of a message body encounters a character set which 580is not understood by Perl's Encode module. 581 582=item Error: Data not convertible to a message (type is $type) 583 584An object which is not coercable into a L<Mail::Message::Part|Mail::Message::Part> object was 585passed to the initiation. The data is ignored. 586 587=item Warning: No decoder defined for transfer encoding $name. 588 589The data (message body) is encoded in a way which is not currently understood, 590therefore no decoding (or recoding) can take place. 591 592=item Warning: No encoder defined for transfer encoding $name. 593 594The data (message body) has been decoded, but the required encoding is 595unknown. The decoded data is returned. 596 597=item Error: Package $package does not implement $method. 598 599Fatal error: the specific package (or one of its superclasses) does not 600implement this method where it should. This message means that some other 601related classes do implement this method however the class at hand does 602not. Probably you should investigate this and probably inform the author 603of the package. 604 605=item Error: Unknown criterium $what to select parts. 606 607Valid choices fdr part selections are C<ALL>, C<ACTIVE>, C<DELETED>, 608C<RECURSE> or a code reference. However, some other argument was passed. 609 610=item Warning: Unknown line terminator $eol ignored 611 612=item Error: You cannot use foreachLine on a multipart 613 614L<foreachLine()|Mail::Message::Body::Multipart/"METHODS"> should be used on decoded message bodies only, because 615it would attempt to modify part-headers and separators as well, which is 616clearly not acceptable. 617 618=back 619 620=head1 SEE ALSO 621 622This module is part of Mail-Message distribution version 3.011, 623built on July 27, 2021. Website: F<http://perl.overmeer.net/CPAN/> 624 625=head1 LICENSE 626 627Copyrights 2001-2021 by [Mark Overmeer <markov@cpan.org>]. For other contributors see ChangeLog. 628 629This program is free software; you can redistribute it and/or modify it 630under the same terms as Perl itself. 631See F<http://dev.perl.org/licenses/> 632 633