Provided by: libmail-message-perl_3.015-1_all bug

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->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.015, built on December 11,
       2023. Website: http://perl.overmeer.net/CPAN/

LICENSE

       Copyrights 2001-2023 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/