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

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.

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

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.