NAME¶
Mail::Message::Body::Encode - organize general message encodings
SYNOPSIS¶
my Mail::Message $msg = ...;
my $decoded = $msg->decoded;
my $encoded = $msg->encode(mime_type => 'image/gif',
transfer_encoding => 'base64');
my $body = $msg->body;
my $decoded = $body->decoded;
my $encoded = $body->encode(transfer_encoding => '7bit');
DESCRIPTION¶
Manages the message's body encodings and decodings on request of the main
program. This package adds functionality to the Mail::Message::Body class when
the
decoded() or
encode() method is called.
Four types of encodings are handled (in the right order)
- •
- eol encoding
Various operating systems have different ideas about how to encode the line
termination. UNIX uses a LF character, MacOS uses a CR, and Windows uses a
CR/LF combination. Messages which are transported over Internet will
always use the CRLF separator.
- •
- transfer encoding
Messages transmitted over Internet have to be plain ASCII. Complicated
characters and binary files (like images and archives) must be encoded
during transmission to an ASCII representation.
The implementation of the required encoders and decoders is found in the
Mail::Message::TransferEnc set of packages. The related manual page lists
the transfer encodings which are supported.
- •
- mime-type translation
NOT IMPLEMENTED YET
- •
- charset conversion
METHODS¶
Constructing a body¶
- $obj->check()
- Check the content of the body not to include illegal characters. Which
characters are considered illegal depends on the encoding of this body.
A body is returned which is checked. This may be the body where this method
is called upon, but also a new object, when serious changes had to be
made. If the check could not be made, because the decoder is not defined,
then "undef" is returned.
- $obj->encode(%options)
- Encode (translate) a Mail::Message::Body into a different format. See the
DESCRIPTION above. Options which are not specified will not trigger
conversions.
-Option --Default
charset PERL if text
mime_type undef
result_type <same as source>
transfer_encoding undef
- charset => CODESET|'PERL'
- If the CODESET is explicitly specified (for instance
"iso-8859-10", then the data is interpreted as raw bytes (blob),
not as text. However, in case of "PERL", it is considered to be
an internal representation of characters (either latin1 or Perl's utf8
--not the same as utf-8--, you should not know).
- mime_type => STRING|FIELD
- Convert into the specified mime type, which can be specified as STRING or
FIELD. The FIELD is a Mail::Message::Field, and the STRING is converted in
such object before use.
- result_type => CLASS
- The type of body to be created when the body is changed to fulfill the
request on re-coding. Also the intermediate stages in the translation
process (if needed) will use this type. CLASS must extend
Mail::Message::Body.
- transfer_encoding => STRING|FIELD
- $obj->encoded()
- Encode the body to a format what is acceptable to transmit or write to a
folder file. This returns the body where this method was called upon when
everything was already prepared, or a new encoded body otherwise. In
either case, the body is checked.
- $obj->unify($body)
- Unify the type of the given $body objects with the type of the called
body. "undef" is returned when unification is impossible. If the
bodies have the same settings, the $body object is returned unchanged.
Examples:
my $bodytype = Mail::Message::Body::Lines;
my $html = $bodytype->new(mime_type=>'text/html', data => []);
my $plain = $bodytype->new(mime_type=>'text/plain', ...);
my $unified = $html->unify($plain);
# $unified is the data of plain translated to html (if possible).
About the payload¶
- $obj->dispositionFilename( [$directory] )
- Returns the name which can be used as filename to store the information in
the indicated $directory. To get a filename, various fields are searched
for "filename" and "name" attributes. Without
$directory, the name found will be returned.
Only the basename of the found name will be used, for security reasons:
otherwise, it may be possible to access other directories than the one
indicated. If no name was found, or the name is already in use, then an
unique name is generated.
- $obj->isBinary()
- Returns true when the un-encoded message is binary data. This information
is retrieved from knowledge provided by MIME::Types.
- $obj->isText()
- Returns true when the un-encoded message contains printable text.
Internals¶
- $obj->addTransferEncHandler( $name, <$class|$object>
)
- Mail::Message::Body->addTransferEncHandler( $name,
<$class|$object> )
- Relate the NAMEd transfer encoding to an OBJECTs or object of the
specified $class. In the latter case, an object of that $class will be
created on the moment that one is needed to do encoding or decoding.
The $class or $object must extend Mail::Message::TransferEnc. It will
replace existing class and object for this $name.
Why aren't you contributing this class to MailBox?
- $obj->getTransferEncHandler($type)
- Get the transfer encoder/decoder which is able to handle $type, or return
undef if there is no such handler.
DIAGNOSTICS¶
- Warning: Charset $name is not known
- The encoding or decoding of a message body encounters a character set
which is not understood by Perl's Encode module.
- Warning: No decoder defined for transfer encoding $name.
- The data (message body) is encoded in a way which is not currently
understood, therefore no decoding (or recoding) can take place.
- Warning: No encoder defined for transfer encoding $name.
- The data (message body) has been decoded, but the required encoding is
unknown. The decoded data is returned.
SEE ALSO¶
This module is part of Mail-Box distribution version 2.117, built on August 24,
2014. Website:
http://perl.overmeer.net/mailbox/
LICENSE¶
Copyrights 2001-2014 by [Mark Overmeer]. For other contributors see ChangeLog.
This program is free software; you can redistribute it and/or modify it under
the same terms as Perl itself. See
http://www.perl.com/perl/misc/Artistic.html
