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.

cpanm Mail::Box

perl -MCPAN -e shell
install Mail::Box