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

NAME

Mail::Message::Head - the header of one message

CLASS INHERITANCE

Mail::Message::Head is a Mail::Reporter

Mail::Message::Head is extended by Mail::Message::Head::Complete Mail::Message::Head::Delayed Mail::Message::Head::Subset

SYNOPSIS

my $head = Mail::Message::Head->new;
$head->add('From: me@localhost');
$head->add(From => 'me@localhost');
$head->add(Mail::Message::Field->new(From => 'me'));
my Mail::Message::Field $subject = $head->get('subject');
my Mail::Message::Field @rec = $head->get('received');
$head->delete('From');

DESCRIPTION

Mail::Message::Head MIME headers are part of Mail::Message messages, which are stored by Mail::Box folders.

The header of a MIME message object contains a set of lines, which are called fields (by default represented by Mail::Message::Field objects). Dependent on the situation, the knowledge about the fields can be in one of three situations, each represented by a sub-class of this module:

  • Mail::Message::Head::Complete

    In this case, it is sure that all knowledge about the header is available. When you get() information from the header and it is not there, it will never be there.

  • Mail::Message::Head::Subset

    There is no certainty whether all header lines are known (probably not). This may be caused as result of reading a fast index file, as described in Mail::Box::MH::Index. The object is automatically transformed into a Mail::Message::Head::Complete when all header lines must be known.

  • Mail::Message::Head::Delayed

    In this case, there is no single field known. Access to this header will always trigger the loading of the full header.

On this page, the general methods which are available on any header are described. Read about differences in the sub-class specific pages.

METHODS

Initiation

build FIELDS

A fast way to construct a header with many lines. The FIELDS are name--content pairs of the header. A header is created, and each pair is added. Doubles are permitted.

Examples:

my $head = Mail::Message::Head->build
 ( From     => 'me@example.com'
 , To       => 'you@anywhere.aq'
 , Received => 'one'
 , Received => 'two'
 );
new OPTIONS

Create a new message header object. The object will store all the fields of a header. When you get information from the header, it will be returned to you as Mail::Message::Field objects, although the fields may be stored differently internally.

If you try to instantiate a Mail::Message::Head, you will automatically be upgraded to a Mail::Message::Head::Complete --a full head.

OPTION               DEFAULT
field_type           'Mail::Message::Field::Fast'
log                  'WARNINGS'
message              undef
modified             <false>
trace                'WARNINGS'
field_type => CLASS

The type of objects that all the fields will have. This must be an extension of Mail::Message::Field.

log => LEVEL

See Mail::Reporter::new(log)

message => MESSAGE

The MESSAGE where this header belongs to. Usually, this is not known at creation of the header, but sometimes it is. If not, call the message() method later to set it.

modified => BOOLEAN
trace => LEVEL

See Mail::Reporter::new(trace)

The Header

isDelayed

Headers may only be partially read, in which case they are called delayed. This method returns true if some header information still needs to be read. Returns false if all header data has been read. Will never trigger completion.

isEmpty

Are there any fields defined in the current header? Be warned that the header will not be loaded for this: delayed headers will return true in any case.

isMultipart

Returns whether the body of the related message is a multipart body. May trigger completion.

message [MESSAGE]

Get (after setting) the message where this header belongs to. This does not trigger completion.

modified [BOOLEAN]

Returns whether the header has been modified after being read, optionally after setting that status first. This will not trigger completion.

Examples:

if($head->modified) { ... }
$head->modified(1);

Access to the Header

get NAME [,INDEX]

Get the data which is related to the field with the NAME. The case of the characters in NAME does not matter.

If there is only one data element defined for the NAME, or if there is an INDEX specified as the second argument, only the specified element will be returned. If the field NAME matches more than one header the return value depends on the context. In LIST context, all values will be returned in the order they are read. In SCALAR context, only the last value will be returned.

Examples:

my $head = Mail::Message::Head->new;
$head->add('Received: abc');
$head->add('Received: xyz');
$head->add('Subject: greetings');

my @rec_list   = $head->get('Received');
my $rec_scalar = $head->get('Received');
print ",@rec_list,$rec_scalar,"     # ,abc xyz, xyz,
print $head->get('Received', 0);    # abc
my @sub_list   = $head->get('Subject');
my $sub_scalar = $head->get('Subject');
print ",@sub_list,$sub_scalar,"     # ,greetings, greetings,
knownNames

Like names(), but only returns the known header fields, which may be less than names() for header types which are partial. names() will trigger completion, where knownNames does not.

printUndisclosed [FILEHANDLE]

Like the usual print(), the header lines are printed to the specified FILEHANDLE, by default the selected filehandle. In this case, however, Bcc and Resent-Bcc lines are included.

Reading and Writing [internals]

addNoRealize FIELD

Add a field, like add() does, but avoid the loading of a possibly partial header. This method does not test the validity of the argument, nor flag the header as changed. This does not trigger completion.

addOrderedFields FIELDS
fileLocation

Returns the location of the header in the file, as a pair begin and end. The begin is the first byte of the header. The end is the first byte after the header.

load

Be sure that the header is loaded. This returns the loaded header object.

moveLocation DISTANCE

Move the registration of the header in the file.

orderedFields

Retuns the fields ordered the way they were read or added.

read PARSER

Read the header information of one message into this header structure. This method is called by the folder object (some Mail::Box sub-class), which passes the PARSER as an argument. Do not call this method yourself!

setNoRealize FIELD

Set a field, but avoid the loading of a possibly partial header as set() does. This method does not test the validity of the argument, nor flag the header as changed. This does not trigger completion.

Logging and Tracing

defaultTrace [LEVEL, [LEVEL]

See Mail::Reporter::defaultTrace()

errors

See Mail::Reporter::errors()

log [LEVEL [,STRINGS]]

See Mail::Reporter::log()

report [LEVEL]

See Mail::Reporter::report()

reportAll [LEVEL]

See Mail::Reporter::reportAll()

trace [LEVEL]

See Mail::Reporter::trace()

warnings

See Mail::Reporter::warnings()

Other Methods

AUTOLOAD

See Mail::Reporter::AUTOLOAD()

DESTROY

See Mail::Reporter::DESTROY()

inGlobalDestruction

See Mail::Reporter::inGlobalDestruction()

logPriority LEVEL

See Mail::Reporter::logPriority()

logSettings

See Mail::Reporter::logSettings()

notImplemented

See Mail::Reporter::notImplemented()

SEE ALSO

A good start to read is Mail::Box-Overview. More documentation and a mailinglist are available from the project's website at http://perl.overmeer.net/mailbox/.

AUTHOR

Mark Overmeer (mark@overmeer.net) with the help of many.

VERSION

This code is beta, version 2.025.

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.