/ 
Mail-Box-2.002
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

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

MMC bounce OPTIONS                    MM modified [BOOL]
MMC build [MESSAGE|BODY], CONTENT        new OPTIONS
MMC buildFromBody BODY, HEADERS       MM nrLines
    copyTo FOLDER                     MM parent
 MM decoded OPTIONS                   MM parts
    delete                            MM print [FILEHANDLE]
    deleted [BOOL]                    MM printUndisclosed [FILEHANDLE]
 MM destinations                     MMC quotePrelude [STRING|FIELD]
 MM encode OPTIONS                   MMC reply OPTIONS
 MR errors                           MMC replySubject STRING
    folder [FOLDER]                   MR report [LEVEL]
 MM from|to|cc|bcc|date               MR reportAll [LEVEL]
 MM get FIELD                         MM send [MAILER], OPTIONS
 MM guessTimestamp                       seqnr [INTEGER]
 MM isDummy                              setLabel LIST
 MM isMultipart                          shortString
 MM isPart                            MM size
    label STRING [ ,STRING ,...]      MM subject
    labels                            MM timestamp
 MR log [LEVEL [,STRINGS]]            MM toplevel
 MM messageId                         MR trace [LEVEL]

The extra methods for extension writers:

MR AUTOLOAD                          MM isDelayed
MM DESTROY                           MR logPriority LEVEL
MM body [BODY]                       MR logSettings
MM clone                             MR notImplemented
MM coerce MESSAGE                    MM read PARSER, [BODYTYPE]
   diskDelete                           readBody PARSER, HEAD [, BO...
MM head [HEAD]                       MM readHead PARSER [,CLASS]
MR inGlobalDestruction               MM storeBody BODY

Methods prefixed with an abbreviation are described in the following manual-pages:

 MM = L<Mail::Message>
 MR = L<Mail::Reporter>
MMC = L<Mail::Message::Construct>

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
labels        Mail::Box::Message   []
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?

  • labels => [ STRING => VALUE, ... ]

    Set the specified labels to their accompanying value. In most cases, this value will only be used as boolean, but it might be more complex.

  • 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.

Label management

Labels are used to store knowledge about handling of the message within the folder. Flags about whether a message was read, replied to, or (in some cases) scheduled for deletion.

setLabel LIST

The LIST is a set of scalars forming key,value pairs.

label STRING [ ,STRING ,...]

Get the value related to the label(s). This returns a list of values, which may be empty, undefined, or a value which evaluates to TRUE.

Example:

if($message->label('seen')) {...}
my ($seen, $current) = $msg->label('seen', 'current');
labels

Returns all known labels. In SCALAR context, it returns the knowledge as reference to a hash. This is a reference to the original data, but you shall *not* change that data directly: call setLabel() for changes!

In LIST context, you get a list of names which are defined. Be warned that they will not all evaluate to true, although most of them will.

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.

Example:

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

METHODS for extension writers

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

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.00_20.

Copyright (c) 2001 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.