MIME::Entity(3)User Contributed Perl DocumentationMIME::Entity(3)NAMEMIME::Entity - class for parsed-and-decoded MIME message
WARNING: This code is in an evaluation phase until 1
August 1996. Depending on any comments/complaints
received before this cutoff date, the interface may change
in a non-backwards-compatible manner.
DESCRIPTION
This package provides a class for representing MIME
message entities, as specified in RFC 1521, Multipurpose
Internet Mail Extensions.
Here are some excerpts from RFC-1521 explaining the
terminology: each is accompanied by the equivalent in
MIME:: terms:
Message
From RFC-1521:
The term "message", when not further qualified, means either the
(complete or "top-level") message being transferred on a network, or
a message encapsulated in a body of type "message".
There currently is no explicit package for messages;
under MIME::, messages may be read in from readable
files or filehandles. A future extension will allow
them to be read from any object reference that
responds to a special "next line" method.
Body part
From RFC-1521:
The term "body part", in this document, means one of the parts of the
body of a multipart entity. A body part has a header and a body, so
it makes sense to speak about the body of a body part.
Since a body part is just a kind of entity (see
below), a body part is represented by an instance of
MIME::Entity.
Entity
From RFC-1521:
The term "entity", in this document, means either a message or a body
part. All kinds of entities share the property that they have a
header and a body.
An entity is represented by an instance of
MIME::Entity. There are instance methods for
recovering the header (a MIME::Head) and the body (see
below).
28/Aug/1996 perl 5.005, patch 03 1
MIME::Entity(3)User Contributed Perl DocumentationMIME::Entity(3)
Body
From RFC-1521:
The term "body", when not further qualified, means the body of an
entity, that is the body of either a message or of a body part.
Well, this is a toughie. Both Mail::Internet (1.17)
and Mail::MIME (1.03) represent message bodies in-
core; unfortunately, this is not always the best way
to handle things, especially for MIME streams that
contain multi-megabyte tar files.
PUBLIC INTERFACE
Constructors and converters
new Class method. Create a new, empty MIME entity.
from_mail MAIL
Class method. Create a new MIME entity from a
MAIL::Internet object. Currently unimplemented.
to_mail
Instance method. Convert a MIME entity to a
MAIL::Internet object. Currently unimplemented.
Instance methods
add_part
Assuming we are a multipart message, add a body part
(a MIME::Entity) to the array of body parts. Do not
call this for single-part messages; i.e., don't call
it unless the header has a "multipart" content-type.
body OPTVALUE
Get or set the path to the file containing the body.
If OPTVALUE is not given, the current body file is
returned. If OPTVALUE is given, the body file is set
to the new value, and the previous value is returned.
head OPTVALUE
Get or set the head.
If OPTVALUE is not given, the current head is
returned. If OPTVALUE is given, the head is set to
the new value, and the previous value is returned.
is_multipart
Does this entity's MIME type indicate that it's a
multipart entity? Returns undef (false) if the answer
couldn't be determined, 0 (false) if it was determined
to be false, and true otherwise.
28/Aug/1996 perl 5.005, patch 03 2
MIME::Entity(3)User Contributed Perl DocumentationMIME::Entity(3)
Note that this says nothing about whether or not parts
were extracted.
mime_type
A purely-for-convenience method. This simply relays
the request to the associated MIME::Head object. The
following are identical:
$x = $entity->mime_type;
$x = $entity->head->mime_type;
If there is no head, returns undef in a scalar context
and the empty array in a list context.
Note that, while parsed entities still have MIME
types, they do not have MIME encodings, or MIME
versions, or fields, etc., etc... for those
attributes, you still have to go to the head
explicitly.
parts
Return an array of all sub parts (each of which is a
MIME::Entity), or the empty array if there are none.
For single-part messages, the empty array will be
returned. For multipart messages, the preamble and
epilogue parts are not in the list! If you want them,
use all_parts() instead.
dump_skeleton FILEHANDLE
Dump the skeleton of the entity to the given
FILEHANDLE, or to the currently-selected one if none
given.
UNDER THE HOOD
A MIME::Entity is composed of the following elements:
o A head, which is a reference to a MIME::Head object.
o A body, which (currently) is a path to a file
containing the decoded body. It is possible for a
multipart entity to have a body; this simply means
that the body file contains a MIME message that hasn't
yet been split into its component parts.
o A list of zero or more parts, each of which is a
MIME::Entity object. The number of parts will only be
nonzero if the content-type is some subtype of
"multipart".
DESIGN ISSUES28/Aug/1996 perl 5.005, patch 03 3
MIME::Entity(3)User Contributed Perl DocumentationMIME::Entity(3)
To subclass or not to subclass?
When I rewrote this module for the CPAN, I agonized for a
long time about whether or not it really should just be a
subclass of Mail::Internet (or the experimental
Mail::MIME). There were plusses:
o Software reuse.
o Inheritance of the mail-sending utilities.
o Elimination and stamping out of repetitive
redundancies.
And, unfortunately, minuses:
o The Mail::Internet model of messages as being short
enough to fit into in-core arrays is excellent for
most email applications; however, it seemed ill-suited
for generic MIME applications, where MIME streams
could be megabytes long.
o The current implementation of Mail::Internet (version
1.17) is excellent for certain kinds of header
manipulation; however, the get() method (for
retrieveing a field's value) does a brute-force,
regexp-based search through a linear array of the
field values - worse, with a dynamically-compiled
search pattern. Even given small headers, I was
simply too uncomfortable with this approach for the
MIME header applications, which could be fairly
get()-intensive.
o In my heart of hearts, I honestly feel that the head
should be encapsulated as a first-class object,
separate from any attached body. Notice that this
approach allows the head to be folded into the entity
in the future; that is:
$entity->head->get('subject');
...can work even if MIME::Head objects are eliminated,
and MIME::Entity objects become the ones that handle
the get() method. To do this, we'd simply define
MIME::Entity::head() to return the "self" object,
which would "pretend" to be the "header" object. Like
this:
sub head { $_[0] }
o While MIME streams follow RFC-822 syntax, they are
not, strictly speaking, limited to email messages:
HTTP is an excellent example of non-email-based MIME.
28/Aug/1996 perl 5.005, patch 03 4
MIME::Entity(3)User Contributed Perl DocumentationMIME::Entity(3)
So the inheritance from Mail::Internet was not without
question anyway.
The compromise. Currently, MIME::Head is its own module.
However:
o When a MIME::Head is constructed using read() (or
from_file()), the original parsed header is stored, in
all its flat-text glory, in the MIME::Head object, and
may be recovered via the original_text() method.
o The conversion methods from_mail() and to_mail() are
provided in MIME::Entity class.
Some things just can't be ignored
In multipart messages, the "preamble" is the portion that
precedes the first encapsulation boundary, and the
"epilogue" is the portion that follows the last
encapsulation boundary.
According to RFC-1521:
There appears to be room for additional information prior to the
first encapsulation boundary and following the final boundary. These
areas should generally be left blank, and implementations must ignore
anything that appears before the first boundary or after the last
one.
NOTE: These "preamble" and "epilogue" areas are generally not used
because of the lack of proper typing of these parts and the lack
of clear semantics for handling these areas at gateways,
particularly X.400 gateways. However, rather than leaving the
preamble area blank, many MIME implementations have found this to
be a convenient place to insert an explanatory note for recipients
who read the message with pre-MIME software, since such notes will
be ignored by MIME-compliant software.
In the world of standards-and-practices, that's the
standard. Now for the practice:
Some MIME mailers may incorrectly put a "part" in the
preamble, Since we have to parse over the stuff anyway, in
the future I will allow the parser option of creating
special MIME::Entity objects for the preamble and
epilogue, with bogus MIME::Head objects.
SEE ALSO
MIME::Decoder, MIME::Entity, MIME::Head, MIME::Parser.
AUTHOR
Copyright (c) 1996 by Eryq / eryq@rhine.gsfc.nasa.gov
All rights reserved. This program is free software; you
28/Aug/1996 perl 5.005, patch 03 5
MIME::Entity(3)User Contributed Perl DocumentationMIME::Entity(3)
can redistribute it and/or modify it under the same terms
as Perl itself.
VERSION
$Revision: 1.12 $ $Date: 1996/06/27 01:26:26 $
28/Aug/1996 perl 5.005, patch 03 6