Message::Body::Encode(3)

NAME
Mail::Message::Body::Encode - organize general message encodings

CLASS HIERARCHY
 Mail::Message::TransferEnc
 is a Mail::Reporter

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 a CR, and Windows 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 losts the transfer encodings which are supported.

* mime-type translation
* charset conversion

METHOD INDEX
The general methods for "Mail::Message::Body::Encode" objects:

      check                                isBinary
      encode OPTIONS                       isText
      encoded

The extra methods for extension writers:

      addTransferEncHandler NAME,...       unify BODY
      getTransferEncHandler TYPE

METHODS

encode OPTIONS
    Encode (translate) a "Mail::Message::Body" object into a different format. See the DESCRIPTION above. Options which are not specified will not trigger conversions.

     OPTION            DESCRIBED IN         DEFAULT
     charset           Mail::Message::Body  undef
     mime_type         Mail::Message::Body  undef
     result_type       Mail::Message::Body  <same as source>
     transfer_encoding Mail::Message::Body  undef

    * charset => STRING
    * 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 fulfil 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
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.

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.

isBinary
    Returns true when the un-encoded message is binary data. This information is retreived from knowledge provided by MIME::Types.

isText
    Returns true when the un-encoded message contains printable text.

METHODS for extension writers

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).

getTransferEncHandler TYPE
    Get the transfer encoder/decoder which is able to handle TYPE, or return undef if there is no such handler.

addTransferEncHandler NAME, CLASS|OBJECT
    (Class or instance method) 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 "Mail::Box"?

SEE ALSO
Mail::Box-Overview

For support and additional documentation, see http://perl.overmeer.net/mailbox/

AUTHOR
Mark Overmeer (mailbox@overmeer.net). All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

VERSION
This code is beta, version 2.018.

Copyright (c) 2001-2002 Mark Overmeer. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.