Mail::Message::Body::Encode(3) User Contributed Perl Documentation
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)
o 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.
o 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.
o mime-type translation
NOT IMPLEMENTED YET
o charset conversion
METHODS
Constructing a body
$obj->charsetDetect(%options)
[3.013] This is tricky. It is hard to detect whether the body
originates from the program, or from an external source. And what
about a database database? are those octets or strings? Please
read "Autodetection of character-set" in Mail::Message::Body.
-Option --Default
external <false>
external => BOOLEAN
Do only consider externally valid character-sets, implicitly:
"PERL" is not an acceptable answer.
Mail::Message::Body->charsetDetectAlgorithm( [CODE|undef|METHOD] )
[3.013] When a body object does not specify its character-set, but
that detail is required, then it gets autodetected. The default
algorithm is implemented in charsetDetect(). You may change this
default algorithm, or pass option "charset_detect" for each call to
encode().
When you call this method with an explicit "undef", you reset the
default. (Without parameter) the current algorithm (CODE or method
name) is returned.
$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
charset_detect <built-in>
mime_type undef
result_type <same as source>
transfer_encoding undef
charset => CHARSET|'PERL'
Only applies when the mime_type is textual.
If the CHARSET is explicitly specified (for instance
"iso-8859-10", then the data is being 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
want to know).
This setting overrules the charset attribute in the mime_type
FIELD.
charset_detect => CODE
[3.013] When the body does not contain an explicit charset
specification, then the RFC says it is "us-ascii". In reality,
this is not true: it is just an unknown character set. This often
happens when text files are included as attachment, for instance
a footer attachment.
When you want to be smarter than the default charset detector,
you can provide your own function for this parameter. The
function will get the transfer-decoded version of this body. You
can change the default globally via charsetDetectAlgorithm().
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-object,
representing a "Content-Type" mime header. The STRING must be
valid content for such header, and will be converted into a FIELD
object.
The FIELD may contain attributes. Usually, it has a "charset"
attribute, which explains the CHARSET of the content after
content transfer decoding. The "charset" option will update/add
this attribute. Otherwise (hopefully in rare cases) the CHARSET
will be auto-detected when the body gets decoded.
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(%options)
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.
-Option --Default
charset_detect <the default>
charset_detect => CODE
See charsetDetectAlgorithm().
$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] )
Various fields are searched for "filename" and "name" attributes.
Without $directory, the name found will be returned unmodified.
When a $directory is given, a filename is composed. For security
reasons, only the basename of the found name gets used and many
potentially dangerous characters removed. If no name was found, or
when the found name is already in use, then an unique name is
generated.
Don't forget to read RFC6266 section 4.3 for the security aspects
in your email application.
$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-Message distribution version 3.016, built
on November 27, 2024. Website: http://perl.overmeer.net/CPAN/
LICENSE
Copyrights 2001-2024 by [Mark Overmeer <markov@cpan.org>]. 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://dev.perl.org/licenses/
perl v5.40.0 2024-11-30 Mail::Message::Body::Encode(3)