MIME::Entity man page on BSDi

Man page or keyword search:  
man Server   6284 pages
apropos Keyword Search (all sections)
Output format
BSDi logo
[printable version]



MIME::Entity(3)User Contributed Perl DocumentationMIME::Entity(3)

NAME
       MIME::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 ISSUES

28/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

[top]

List of man pages available for BSDi

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net