Home | MIME::Body | MIME::Decoder | MIME::Entity | MIME::Head |
MIME::IO | MIME::Latin1 | MIME::Parser | MIME::ParserBase | |
MIME::ToolUtils |
MIME::
|
$ent = new MIME::Entity [ "Subject: Greetings\n", "Content-type: text/plain\n", "Content-transfer-encoding: 7bit\n", "\n", "Hi there!\n", "Bye there!\n" ]; $ent->print(\*STDOUT);
Create a document for an ordinary 7-bit ASCII text file (lots of stuff is defaulted for us):
$msg = build MIME::Entity Path=>"english-msg.txt"; $msg->print(\*STDOUT);
Create a document for a text file with 8-bit (Latin-1) characters:
$msg = build MIME::Entity Path =>"french-msg.txt", Encoding =>"quoted-printable"; $msg->print(\*STDOUT);
Create a document for a GIF file (the description is completely optional, and note that we have to specify content-type and encoding since they're not the default values):
$gif = build MIME::Entity Description => "A pretty picture", Path => "./docs/mime-sm.gif", Type => "image/gif", Encoding => "base64"; $gif->print(\*STDOUT);
Create a multipart message (could it be much easier?)
# Create the top-level: $top = build MIME::Entity Type=>"multipart/mixed"; # Attachment #1: a simple text document: attach $top Path=>"./testin/short.txt"; # Attachment #2: a GIF file: attach $top Path => "./docs/mime-sm.gif", Type => "image/gif", Encoding => "base64"; # Maybe add some mail-related stuff... $top->head->add('from', "me@myhost.com"); $top->head->add('to', "you@yourhost.com"); $top->head->add('subject', "Hello, nurse!"); # Output: $top->print(\*STDOUT);
Extract information from MIME entities:
# Get the head, a MIME::Head: $head = $ent->head; # Get the body, as a MIME::Body; $bodyh = $ent->bodyhandle;
See MIME::Parser for additional examples of usage.
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:
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.
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.
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).
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.
If SOURCE is an ARRAYREF, it is assumed to be an array of lines that will be used to create both the header and an in-core body.
Else, if SOURCE is defined, it is assumed to be a filehandle from which the header and in-core body is to be read.
Note: in either case, the body will not be parsed: merely read!
$ent = build MIME::Entity Type => "image/gif", Encoding => "base64", Path => "/path/to/xyz12345.gif", Filename => "saveme.gif";
And like this to build a ``multipart'' entity:
$ent = build MIME::Entity Type => "multipart/mixed", Boundary => "---1234567";
A minimal MIME header will be created. The params are:
"7bit"
as per RFC-1521. Do yourself a favor: put it in.
"text/plain"
as per RFC-1521. Do yourself a favor: put it in.
"multipart"
content-type.
$entity->add_part(ref($entity)->build(PARAMHASH));
Except that it's a lot nicer to look at.
If VALUE
is not
given, the current body file is returned. If VALUE
is
given, the body file is set to the new value, and the previous value is
returned.
Provided for compatibility with Mail::Internet, and it might not be as efficient as you'd like. Also, it's somewhat silly/wrongheaded for binary bodies, like GIFs and tar files.
bodyhandle()
method to get and use a MIME::Body. The content-type of the entity will tell
you whether that body is best read as text (via getline())
or
raw data (via read()).
If VALUE
is not
given, the current bodyhandle is returned. If VALUE
is
given, the bodyhandle is set to the new value, and the previous value is
returned.
If there is no VALUE given, returns the current head. If none exists, an empty instance of MIME::Head is created, set, and returned.
Note: This is a patch over a bug in Mail::Internet, which doesn't provide a method for setting the head to some given object.
Note that this says nothing about whether or not parts were extracted.
$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.
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.
If a single-part entity, the header and the body are both output, with the body being output according to the encoding specified by the header.
If a multipart entity, this is invoked recursively on all its parts, with appropriate boundaries and a preamble generated for you.
See print_body()
for an important note on how the body is output.
Important note:
the body is output according to the encoding specified by the header ('binary'
if no encoding given). This means that the following code:
$ent = new MIME::Entity ["Subject: Greetings\n", "Content-transfer-encoding: base64\n", "\n", "Hi there!\n", "Bye there!\n" ]; $ent->print; # uses print_body() internally
Prints this:
Subject: Greetings Content-transfer-encoding: base64
SGkgdGhlcmUhCkJ5ZSB0aGVyZSEK
The body is stored
in an unencoded form; however, the idea is that the transfer encoding is
used to determine how it should be output.
This means that the print()
method is always guaranteed to get you a sendmail-ready stream whose body
is consistent with its head.
If you want the raw body data to be output, you can either read it from the bodyhandle yourself, or use:
$ent->bodyhandle->print;
which uses read()
calls to extract the information, and thus
will work with both text and binary bodies.
"multipart"
.
Note that, in 2.0+, a multipart entity does not have a body. Of course, any/all of its component parts can have bodies.
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 may allow the parser option of creating special MIME::Entity objects for the preamble and epilogue, with bogus MIME::Head objects.
For now, though, we're MIME-compliant, so I probably won't change how we work.
All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.