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