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-Message distribution version 3.006,  built  on  January  24,  2018.  Website:
       http://perl.overmeer.net/CPAN/

LICENSE

       Copyrights 2001-2018 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://dev.perl.org/licenses/

perl v5.26.1                                       2018-02-14                   Mail::Message::Body::Encode(3pm)