1=encoding utf8 2 3=head1 NAME 4 5Mail::Box::Message::Destructed - a destructed message 6 7=head1 INHERITANCE 8 9 Mail::Box::Message::Destructed 10 is a Mail::Box::Message 11 is a Mail::Message 12 is a Mail::Reporter 13 14=head1 SYNOPSIS 15 16 $folder->message(3)->destruct; 17 18=head1 DESCRIPTION 19 20When a message folder is read, each message will be parsed into Perl 21structures. Especially the header structure can consume a huge amount 22of memory (message bodies can be moved to external temporary files). 23Destructed messages have forcefully cleaned-up all header and body 24information, and are therefore much smaller. Some useful information 25is still in the object. 26 27BE WARNED: once a message is destructed, it cannot be revived. Destructing 28enforces irreversable deletion from the folder. If you have a folder opened 29for read-only, the message will stay in that folder, but otherwise it may 30be deleted. 31 32Extends L<"DESCRIPTION" in Mail::Box::Message|Mail::Box::Message/"DESCRIPTION">. 33 34=head1 METHODS 35 36Extends L<"METHODS" in Mail::Box::Message|Mail::Box::Message/"METHODS">. 37 38=head2 Constructors 39 40Extends L<"Constructors" in Mail::Box::Message|Mail::Box::Message/"Constructors">. 41 42=over 4 43 44=item $obj-E<gt>B<clone>(%options) 45 46Inherited, see L<Mail::Message/"Constructors"> 47 48=item Mail::Box::Message::Destructed-E<gt>B<new>($message_id, %options) 49 50You cannot instantiate a destructed message object. Destruction is 51done by calling L<Mail::Box::Message::destruct()|Mail::Box::Message/"Cleanup">. 52 53 -Option --Defined in --Default 54 body Mail::Message undef 55 body_type Mail::Box::Message <from folder> 56 deleted Mail::Message <false> 57 field_type Mail::Message undef 58 folder Mail::Box::Message <required> 59 head Mail::Message undef 60 head_type Mail::Message Mail::Message::Head::Complete 61 labels Mail::Message {} 62 log Mail::Reporter 'WARNINGS' 63 messageId Mail::Message undef 64 modified Mail::Message <false> 65 size Mail::Box::Message undef 66 trace Mail::Reporter 'WARNINGS' 67 trusted Mail::Message <false> 68 69=over 2 70 71=item body => OBJECT 72 73=item body_type => CODE|CLASS 74 75=item deleted => BOOLEAN 76 77=item field_type => CLASS 78 79=item folder => FOLDER 80 81=item head => OBJECT 82 83=item head_type => CLASS 84 85=item labels => ARRAY|HASH 86 87=item log => LEVEL 88 89=item messageId => STRING 90 91=item modified => BOOLEAN 92 93=item size => INTEGER 94 95=item trace => LEVEL 96 97=item trusted => BOOLEAN 98 99=back 100 101=back 102 103=head2 Constructing a message 104 105Extends L<"Constructing a message" in Mail::Box::Message|Mail::Box::Message/"Constructing a message">. 106 107=over 4 108 109=item $obj-E<gt>B<bounce>( [<$rg_object|%options>] ) 110 111Inherited, see L<Mail::Message::Construct::Bounce/"Constructing a message"> 112 113=item Mail::Box::Message::Destructed-E<gt>B<build>( [$message|$part|$body], $content ) 114 115Inherited, see L<Mail::Message::Construct::Build/"Constructing a message"> 116 117=item Mail::Box::Message::Destructed-E<gt>B<buildFromBody>($body, [$head], $headers) 118 119Inherited, see L<Mail::Message::Construct::Build/"Constructing a message"> 120 121=item $obj-E<gt>B<forward>(%options) 122 123Inherited, see L<Mail::Message::Construct::Forward/"Constructing a message"> 124 125=item $obj-E<gt>B<forwardAttach>(%options) 126 127Inherited, see L<Mail::Message::Construct::Forward/"Constructing a message"> 128 129=item $obj-E<gt>B<forwardEncapsulate>(%options) 130 131Inherited, see L<Mail::Message::Construct::Forward/"Constructing a message"> 132 133=item $obj-E<gt>B<forwardInline>(%options) 134 135Inherited, see L<Mail::Message::Construct::Forward/"Constructing a message"> 136 137=item $obj-E<gt>B<forwardNo>(%options) 138 139Inherited, see L<Mail::Message::Construct::Forward/"Constructing a message"> 140 141=item $obj-E<gt>B<forwardPostlude>() 142 143Inherited, see L<Mail::Message::Construct::Forward/"Constructing a message"> 144 145=item $obj-E<gt>B<forwardPrelude>() 146 147Inherited, see L<Mail::Message::Construct::Forward/"Constructing a message"> 148 149=item $obj-E<gt>B<forwardSubject>(STRING) 150 151Inherited, see L<Mail::Message::Construct::Forward/"Constructing a message"> 152 153=item Mail::Box::Message::Destructed-E<gt>B<read>($fh|STRING|SCALAR|ARRAY, %options) 154 155Inherited, see L<Mail::Message::Construct::Read/"Constructing a message"> 156 157=item $obj-E<gt>B<rebuild>(%options) 158 159Inherited, see L<Mail::Message::Construct::Rebuild/"Constructing a message"> 160 161=item $obj-E<gt>B<reply>(%options) 162 163Inherited, see L<Mail::Message::Construct::Reply/"Constructing a message"> 164 165=item $obj-E<gt>B<replyPrelude>( [STRING|$field|$address|ARRAY-$of-$things] ) 166 167Inherited, see L<Mail::Message::Construct::Reply/"Constructing a message"> 168 169=item $obj-E<gt>B<replySubject>(STRING) 170 171=item Mail::Box::Message::Destructed-E<gt>B<replySubject>(STRING) 172 173Inherited, see L<Mail::Message::Construct::Reply/"Constructing a message"> 174 175=back 176 177=head2 The message 178 179Extends L<"The message" in Mail::Box::Message|Mail::Box::Message/"The message">. 180 181=over 4 182 183=item $obj-E<gt>B<container>() 184 185Inherited, see L<Mail::Message/"The message"> 186 187=item $obj-E<gt>B<copyTo>($folder, %options) 188 189Inherited, see L<Mail::Box::Message/"The message"> 190 191=item $obj-E<gt>B<folder>( [$folder] ) 192 193Inherited, see L<Mail::Box::Message/"The message"> 194 195=item $obj-E<gt>B<isDummy>() 196 197Inherited, see L<Mail::Message/"The message"> 198 199=item $obj-E<gt>B<isPart>() 200 201Inherited, see L<Mail::Message/"The message"> 202 203=item $obj-E<gt>B<messageId>() 204 205Inherited, see L<Mail::Message/"The message"> 206 207=item $obj-E<gt>B<moveTo>($folder, %options) 208 209Inherited, see L<Mail::Box::Message/"The message"> 210 211=item $obj-E<gt>B<partNumber>() 212 213Inherited, see L<Mail::Message/"The message"> 214 215=item $obj-E<gt>B<print>( [$fh] ) 216 217Inherited, see L<Mail::Message/"The message"> 218 219=item $obj-E<gt>B<send>( [$mailer], %options ) 220 221Inherited, see L<Mail::Message/"The message"> 222 223=item $obj-E<gt>B<seqnr>( [$integer] ) 224 225Inherited, see L<Mail::Box::Message/"The message"> 226 227=item $obj-E<gt>B<size>() 228 229Inherited, see L<Mail::Message/"The message"> 230 231=item $obj-E<gt>B<toplevel>() 232 233Inherited, see L<Mail::Message/"The message"> 234 235=item $obj-E<gt>B<write>( [$fh] ) 236 237Inherited, see L<Mail::Message/"The message"> 238 239=back 240 241=head2 The header 242 243Extends L<"The header" in Mail::Box::Message|Mail::Box::Message/"The header">. 244 245=over 4 246 247=item $obj-E<gt>B<bcc>() 248 249Inherited, see L<Mail::Message/"The header"> 250 251=item $obj-E<gt>B<cc>() 252 253Inherited, see L<Mail::Message/"The header"> 254 255=item $obj-E<gt>B<date>() 256 257Inherited, see L<Mail::Message/"The header"> 258 259=item $obj-E<gt>B<destinations>() 260 261Inherited, see L<Mail::Message/"The header"> 262 263=item $obj-E<gt>B<from>() 264 265Inherited, see L<Mail::Message/"The header"> 266 267=item $obj-E<gt>B<get>($fieldname) 268 269Inherited, see L<Mail::Message/"The header"> 270 271=item $obj-E<gt>B<guessTimestamp>() 272 273Inherited, see L<Mail::Message/"The header"> 274 275=item $obj-E<gt>B<head>( [$head] ) 276 277When C<undef> is specified for $head, no change has to take place and 278the method returns silently. In all other cases, this method will 279complain that the header has been removed. 280 281=item $obj-E<gt>B<nrLines>() 282 283Inherited, see L<Mail::Message/"The header"> 284 285=item $obj-E<gt>B<sender>() 286 287Inherited, see L<Mail::Message/"The header"> 288 289=item $obj-E<gt>B<study>($fieldname) 290 291Inherited, see L<Mail::Message/"The header"> 292 293=item $obj-E<gt>B<subject>() 294 295Inherited, see L<Mail::Message/"The header"> 296 297=item $obj-E<gt>B<timestamp>() 298 299Inherited, see L<Mail::Message/"The header"> 300 301=item $obj-E<gt>B<to>() 302 303Inherited, see L<Mail::Message/"The header"> 304 305=back 306 307=head2 The body 308 309Extends L<"The body" in Mail::Box::Message|Mail::Box::Message/"The body">. 310 311=over 4 312 313=item $obj-E<gt>B<body>( [$body] ) 314 315When C<undef> is specified for $body, no change has to take place and 316the method returns silently. In all other cases, this method will 317complain that the body data has been removed. 318 319=item $obj-E<gt>B<contentType>() 320 321Inherited, see L<Mail::Message/"The body"> 322 323=item $obj-E<gt>B<decoded>(%options) 324 325Inherited, see L<Mail::Message/"The body"> 326 327=item $obj-E<gt>B<encode>(%options) 328 329Inherited, see L<Mail::Message/"The body"> 330 331=item $obj-E<gt>B<isMultipart>() 332 333Inherited, see L<Mail::Message/"The body"> 334 335=item $obj-E<gt>B<isNested>() 336 337Inherited, see L<Mail::Message/"The body"> 338 339=item $obj-E<gt>B<parts>( [<'ALL'|'ACTIVE'|'DELETED'|'RECURSE'|$filter>] ) 340 341Inherited, see L<Mail::Message/"The body"> 342 343=back 344 345=head2 Flags 346 347Extends L<"Flags" in Mail::Box::Message|Mail::Box::Message/"Flags">. 348 349=over 4 350 351=item $obj-E<gt>B<delete>() 352 353Inherited, see L<Mail::Message/"Flags"> 354 355=item $obj-E<gt>B<deleted>( [BOOLEAN] ) 356 357Inherited, see L<Mail::Message/"Flags"> 358 359=item $obj-E<gt>B<isDeleted>() 360 361Inherited, see L<Mail::Message/"Flags"> 362 363=item $obj-E<gt>B<isModified>() 364 365Inherited, see L<Mail::Message/"Flags"> 366 367=item $obj-E<gt>B<label>($label|PAIRS) 368 369It is possible to delete a destructed message, but not to undelete it. 370 371=item $obj-E<gt>B<labels>() 372 373Inherited, see L<Mail::Message/"Flags"> 374 375=item $obj-E<gt>B<labelsToStatus>() 376 377Inherited, see L<Mail::Message/"Flags"> 378 379=item $obj-E<gt>B<modified>( [BOOLEAN] ) 380 381Inherited, see L<Mail::Message/"Flags"> 382 383=item $obj-E<gt>B<statusToLabels>() 384 385Inherited, see L<Mail::Message/"Flags"> 386 387=back 388 389=head2 The whole message as text 390 391Extends L<"The whole message as text" in Mail::Box::Message|Mail::Box::Message/"The whole message as text">. 392 393=over 4 394 395=item $obj-E<gt>B<file>() 396 397Inherited, see L<Mail::Message::Construct::Text/"The whole message as text"> 398 399=item $obj-E<gt>B<lines>() 400 401Inherited, see L<Mail::Message::Construct::Text/"The whole message as text"> 402 403=item $obj-E<gt>B<printStructure>( [$fh|undef],[$indent] ) 404 405Inherited, see L<Mail::Message::Construct::Text/"The whole message as text"> 406 407=item $obj-E<gt>B<string>() 408 409Inherited, see L<Mail::Message::Construct::Text/"The whole message as text"> 410 411=back 412 413=head2 Internals 414 415Extends L<"Internals" in Mail::Box::Message|Mail::Box::Message/"Internals">. 416 417=over 4 418 419=item $obj-E<gt>B<clonedFrom>() 420 421Inherited, see L<Mail::Message/"Internals"> 422 423=item Mail::Box::Message::Destructed-E<gt>B<coerce>($message) 424 425Coerce a L<Mail::Box::Message|Mail::Box::Message> into destruction. 426 427example: of coercion to death 428 429 Mail::Box::Message::Destructed->coerce($folder->message(1)); 430 $folder->message(1)->destruct; # same 431 432 my $msg = $folder->message(1); 433 Mail::Box::Message::Destructed->coerce($msg); 434 $msg->destruct; # same 435 436=item $obj-E<gt>B<diskDelete>() 437 438Inherited, see L<Mail::Box::Message/"Internals"> 439 440=item $obj-E<gt>B<isDelayed>() 441 442Inherited, see L<Mail::Message/"Internals"> 443 444=item $obj-E<gt>B<readBody>( $parser, $head, [$bodytype] ) 445 446Inherited, see L<Mail::Box::Message/"Internals"> 447 448=item $obj-E<gt>B<readFromParser>( $parser, [$bodytype] ) 449 450Inherited, see L<Mail::Message/"Internals"> 451 452=item $obj-E<gt>B<readHead>( $parser, [$class] ) 453 454Inherited, see L<Mail::Message/"Internals"> 455 456=item $obj-E<gt>B<recursiveRebuildPart>($part, %options) 457 458Inherited, see L<Mail::Message::Construct::Rebuild/"Internals"> 459 460=item $obj-E<gt>B<storeBody>($body) 461 462Inherited, see L<Mail::Message/"Internals"> 463 464=item $obj-E<gt>B<takeMessageId>( [STRING] ) 465 466Inherited, see L<Mail::Message/"Internals"> 467 468=back 469 470=head2 Error handling 471 472Extends L<"Error handling" in Mail::Box::Message|Mail::Box::Message/"Error handling">. 473 474=over 4 475 476=item $obj-E<gt>B<AUTOLOAD>() 477 478Inherited, see L<Mail::Message::Construct/"METHODS"> 479 480=item $obj-E<gt>B<addReport>($object) 481 482Inherited, see L<Mail::Reporter/"Error handling"> 483 484=item $obj-E<gt>B<defaultTrace>( [$level]|[$loglevel, $tracelevel]|[$level, $callback] ) 485 486=item Mail::Box::Message::Destructed-E<gt>B<defaultTrace>( [$level]|[$loglevel, $tracelevel]|[$level, $callback] ) 487 488Inherited, see L<Mail::Reporter/"Error handling"> 489 490=item $obj-E<gt>B<errors>() 491 492Inherited, see L<Mail::Reporter/"Error handling"> 493 494=item $obj-E<gt>B<log>( [$level, [$strings]] ) 495 496=item Mail::Box::Message::Destructed-E<gt>B<log>( [$level, [$strings]] ) 497 498Inherited, see L<Mail::Reporter/"Error handling"> 499 500=item $obj-E<gt>B<logPriority>($level) 501 502=item Mail::Box::Message::Destructed-E<gt>B<logPriority>($level) 503 504Inherited, see L<Mail::Reporter/"Error handling"> 505 506=item $obj-E<gt>B<logSettings>() 507 508Inherited, see L<Mail::Reporter/"Error handling"> 509 510=item $obj-E<gt>B<notImplemented>() 511 512Inherited, see L<Mail::Reporter/"Error handling"> 513 514=item $obj-E<gt>B<report>( [$level] ) 515 516Inherited, see L<Mail::Reporter/"Error handling"> 517 518=item $obj-E<gt>B<reportAll>( [$level] ) 519 520Inherited, see L<Mail::Reporter/"Error handling"> 521 522=item $obj-E<gt>B<shortSize>( [$value] ) 523 524=item Mail::Box::Message::Destructed-E<gt>B<shortSize>( [$value] ) 525 526Inherited, see L<Mail::Message/"Error handling"> 527 528=item $obj-E<gt>B<shortString>() 529 530Inherited, see L<Mail::Message/"Error handling"> 531 532=item $obj-E<gt>B<trace>( [$level] ) 533 534Inherited, see L<Mail::Reporter/"Error handling"> 535 536=item $obj-E<gt>B<warnings>() 537 538Inherited, see L<Mail::Reporter/"Error handling"> 539 540=back 541 542=head2 Cleanup 543 544Extends L<"Cleanup" in Mail::Box::Message|Mail::Box::Message/"Cleanup">. 545 546=over 4 547 548=item $obj-E<gt>B<DESTROY>() 549 550Inherited, see L<Mail::Reporter/"Cleanup"> 551 552=item $obj-E<gt>B<destruct>() 553 554Inherited, see L<Mail::Box::Message/"Cleanup"> 555 556=back 557 558=head1 DETAILS 559 560Extends L<"DETAILS" in Mail::Box::Message|Mail::Box::Message/"DETAILS">. 561 562=head1 DIAGNOSTICS 563 564=over 4 565 566=item Error: Cannot coerce a (class) into destruction 567 568Only real L<Mail::Box::Message|Mail::Box::Message> objects can get destructed into 569L<Mail::Box::Message::Destructed|Mail::Box::Message::Destructed> objects. L<Mail::Message|Mail::Message> free 570their memory immediately when the last reference is lost. 571 572=item Error: Cannot include forward source as $include. 573 574Unknown alternative for the L<forward(include)|Mail::Message::Construct::Forward/"Constructing a message">. Valid choices are 575C<NO>, C<INLINE>, C<ATTACH>, and C<ENCAPSULATE>. 576 577=item Error: Cannot include reply source as $include. 578 579Unknown alternative for the C<include> option of L<reply()|Mail::Message::Construct::Reply/"Constructing a message">. Valid 580choices are C<NO>, C<INLINE>, and C<ATTACH>. 581 582=item Error: Destructed message has no labels except 'deleted' 583 584=item Error: Destructed messages can not be undeleted 585 586Once a message is destructed, it can not be revived. Destruction is an 587optimization in memory usage: if you need an undelete functionality, then 588you can not use L<Mail::Box::Message::destruct()|Mail::Box::Message/"Cleanup">. 589 590=item Error: Method bounce requires To, Cc, or Bcc 591 592The message L<bounce()|Mail::Message::Construct::Bounce/"Constructing a message"> method forwards a received message off to someone 593else without modification; you must specified it's new destination. 594If you have the urge not to specify any destination, you probably 595are looking for L<reply()|Mail::Message::Construct::Reply/"Constructing a message">. When you wish to modify the content, use 596L<forward()|Mail::Message::Construct::Forward/"Constructing a message">. 597 598=item Error: Method forwardAttach requires a preamble 599 600=item Error: Method forwardEncapsulate requires a preamble 601 602=item Error: No address to create forwarded to. 603 604If a forward message is created, a destination address must be specified. 605 606=item Error: No default mailer found to send message. 607 608The message L<send()|Mail::Message/"The message"> mechanism had not enough information to automatically 609find a mail transfer agent to sent this message. Specify a mailer 610explicitly using the C<via> options. 611 612=item Error: No rebuild rule $name defined. 613 614=item Error: Only build() Mail::Message's; they are not in a folder yet 615 616You may wish to construct a message to be stored in a some kind 617of folder, but you need to do that in two steps. First, create a 618normal L<Mail::Message|Mail::Message>, and then add it to the folder. During this 619L<Mail::Box::addMessage()|Mail::Box/"The folder"> process, the message will get L<coerce()|Mail::Box::Message::Destructed/"METHODS">-d 620into the right message type, adding storage information and the like. 621 622=item Error: Package $package does not implement $method. 623 624Fatal error: the specific package (or one of its superclasses) does not 625implement this method where it should. This message means that some other 626related classes do implement this method however the class at hand does 627not. Probably you should investigate this and probably inform the author 628of the package. 629 630=item Error: You cannot instantiate a destructed message 631 632You cannot instantiate a destructed message object directly. Destruction 633is done by calling L<Mail::Box::Message::destruct()|Mail::Box::Message/"Cleanup"> on any existing 634folder message. 635 636=item Error: You cannot take the head/body of a destructed message 637 638The message originated from a folder, but its memory has been freed-up 639forcefully by means of L<Mail::Box::Message::destruct()|Mail::Box::Message/"Cleanup">. Apparently, 640your program still tries to get to the header or body data after this 641destruction, which is not possible. 642 643=back 644 645=head1 SEE ALSO 646 647This module is part of Mail-Box distribution version 3.009, 648built on August 18, 2020. Website: F<http://perl.overmeer.net/CPAN/> 649 650=head1 LICENSE 651 652Copyrights 2001-2020 by [Mark Overmeer]. For other contributors see ChangeLog. 653 654This program is free software; you can redistribute it and/or modify it 655under the same terms as Perl itself. 656See F<http://dev.perl.org/licenses/> 657 658