/ 
Mail-Box-2.017
River stage one • 8 direct dependents • 8 total dependents
/ Mail::Box::Message

NAME

Mail::Box::Message - manage one message within a mail-folder

CLASS HIERARCHY

Mail::Box::Message
is a Mail::Message + ::Construct
is a Mail::Reporter

SYNOPSIS

# Usually these message objects are created indirectly
use Mail::Box::Manager;
my $manager = Mail::Box::Manager->new;
my $folder  = $manager->open(folder => 'Mail/Drafts');
my $msg     = $folder->message(1);
$msg->delete;
$msg->size;   # and much more

DESCRIPTION

These pages do only describe methods which relate to folders. If you access the knowledge of a message, then read Mail::Message.

During its life, a message will pass through certain stages. These stages were introduced to reduce the access-time to the folder. Changing from stage, the message's body and head objects may change.

The bottom of this page provides more details about the implementation, but first the use.

METHOD INDEX

Methods prefixed with an abbreviation are described in Mail::Message (MM), Mail::Reporter (MR), Mail::Message::Construct (MMC).

The general methods for Mail::Box::Message objects:

 MM bcc                               MR log [LEVEL [,STRINGS]]
MMC bounce OPTIONS                    MM messageId
MMC build [MESSAGE|BODY], CONTENT     MM modified [BOOL]
MMC buildFromBody BODY, HEADERS          new OPTIONS
 MM cc                                MM nrLines
    copyTo FOLDER                     MM parent
 MM date                              MM parts ['ALL'|'ACTIVE'|'DELE...
 MM decoded OPTIONS                   MM print [FILEHANDLE]
    delete                           MMC printStructure [INDENT]
    deleted [BOOL]                   MMC read FILEHANDLE|SCALAR|REF-...
 MM destinations                     MMC reply OPTIONS
 MM encode OPTIONS                   MMC replyPrelude [STRING|FIELD|...
 MR errors                           MMC replySubject STRING
MMC file                              MR report [LEVEL]
    folder [FOLDER]                   MR reportAll [LEVEL]
MMC forward OPTIONS                   MM send [MAILER], OPTIONS
MMC forwardPostlude                      seqnr [INTEGER]
MMC forwardPrelude                       shortString
MMC forwardSubject STRING             MM size
 MM from                             MMC string
 MM get FIELD                         MM subject
 MM guessTimestamp                    MM timestamp
 MM isDummy                           MM to
 MM isMultipart                       MM toplevel
 MM isPart                            MR trace [LEVEL]
 MM label LABEL [,VALUE [LABEL,...    MR warnings
MMC lines

The extra methods for extension writers:

MR AUTOLOAD                          MM labelsToStatus
MM DESTROY                           MR logPriority LEVEL
MM body [BODY]                       MR logSettings
MM clone                             MR notImplemented
   coerce MESSAGE                       readBody PARSER, HEAD [, BO...
   diskDelete                        MM readFromParser PARSER, [BOD...
MM head [HEAD]                       MM readHead PARSER [,CLASS]
MR inGlobalDestruction               MM statusToLabels
MM isDelayed                         MM storeBody BODY
MM labels                            MM takeMessageId [STRING]

METHODS

new OPTIONS

Initialize the runtime variables of a message. The following options are supported:

OPTION        DESCRIBED IN         DEFAULT
body          Mail::Message        undef
deleted       Mail::Box::Message   0
folder        Mail::Box::Message   <required>
head          Mail::Message        undef
head_wrap     Mail::Message        72
log           Mail::Reporter       'WARNINGS'
messageId     Mail::Message        undef
modified      Mail::Message        0
size          Mail::Box::Message   undef
trace         Mail::Reporter       'WARNINGS'
trusted       Mail::Message        0

Only for extension writers:

OPTION        DESCRIBED IN         DEFAULT
body_type     Mail::Box::Message   <from folder>
field_type    Mail::Message        undef
head_type     Mail::Message        'Mail::Message::Head::Complete'

  • folder => FOLDER

    (obligatory) The folder where this message appeared in. The argument is an instance of (a sub-class of) a Mail::Box.

  • body_type => CODE|CLASS

    If the body of a message is used delay-loaded, the message must what type of message to become when it finally gets parsed. The folder which is delaying the load must specify the algorithm to determine that type. See Mail::Box::new(body_type) for a detailed explanation.

  • deleted => BOOL

    Is the file deleted from the start?

  • size => INTEGER

    The size of the message, which includes head and body, but without the message separators which may be used by the folder type.

folder [FOLDER]

In with folder did we detect this message/dummy? This is a reference to the folder-object.

delete

Flag the message to be deleted. The real deletion only takes place on a synchronization of the folder.

Examples:

$message->delete;
delete $message;
deleted [BOOL]

Check or set the deleted flag for this message. This method returns undef (not deleted, false) or the time of deletion (true). With a BOOL argument, the status is changed first.

Examples:

if($message->deleted) {...}
$message->deleted(0);        # undelete
seqnr [INTEGER]

Get (add set) the number of this message is the current folder.

shortString

Convert the message header to a short string, representing the most important facts (for debugging purposes only).

copyTo FOLDER

Copy the message to the indicated opened FOLDER, without deleting the original. The coerced message (the copy) is returned.

Example:

my $draft = $mgr->open(folder => 'Draft');
$message->copyTo($draft);

METHODS for extension writers

coerce MESSAGE

Coerce a message to be included in a folder. The folder itself is not specified, but the type of the message is transformed correctly. The coerced version of the message is returned. When no changes had to be made, the original message is returned.

readBody PARSER, HEAD [, BODYTYPE]

Read the body of one message. The PARSER gives access to the folder file. The HEAD has been read with readHead. The optional BODYTYPE supplies the class name of the body to be created, or a code reference to a routine which can produce a body type based on the head (passed as first argument).

By default, the BODYTYPE will call determineBodyType method of the folder where the message will be added to.

diskDelete

Remove a message from disk. This is not from the folder, but everything else, like parts of the message which are stored externally from the folder.

IMPLEMENTATION

Class structure for messages

As example, the next scheme uses the fake folder-type XYZ, which may be for instance Mbox or MH.

Mail::Box::XYZ::Message
           ^
           |
   Mail::Box::Message
           ^
           |
     Mail::Message
     ::Body ::Head

SEE ALSO

Mail::Box-Overview

For support and additional documentation, see http://perl.overmeer.net/mailbox/

AUTHOR

Mark Overmeer (mailbox@overmeer.net). All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

VERSION

This code is beta, version 2.017.

Copyright (c) 2001-2002 Mark Overmeer. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.