/ 
Mail-Box-2.023
River stage one • 8 direct dependents • 8 total dependents
/ Mail::Message::Body::Encode

NAME

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

CLASS INHERITANCE

Mail::Message::Body has extra code in Mail::Message::Body::Construct has extra code in Mail::Message::Body::Encode

Mail::Message::Body is a Mail::Reporter

Mail::Message::Body is extended by Mail::Message::Body::File Mail::Message::Body::Lines Mail::Message::Body::Multipart Mail::Message::Body::Nested Mail::Message::Body::String

Mail::Message::Body is realized by Mail::Message::Body::Delayed

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

  • charset conversion

METHODS

Initiation

new OPTIONS

See Mail::Message::Body::new()

The Body

clone

See Mail::Message::Body::clone()

decoded OPTIONS

See Mail::Message::Body::decoded()

isDelayed

See Mail::Message::Body::isDelayed()

isMultipart

See Mail::Message::Body::isMultipart()

isNested

See Mail::Message::Body::isNested()

message [MESSAGE]

See Mail::Message::Body::message()

modified [BOOL]

See Mail::Message::Body::modified()

See Mail::Message::Body::print()

About the Payload

charset

See Mail::Message::Body::charset()

checked [BOOLEAN]

See Mail::Message::Body::checked()

disposition [STRING|FIELD]

See Mail::Message::Body::disposition()

eol ['CR'|'LF'|'CRLF'|'NATIVE']

See Mail::Message::Body::eol()

isBinary

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

isText

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

mimeType

See Mail::Message::Body::mimeType()

nrLines

See Mail::Message::Body::nrLines()

size

See Mail::Message::Body::size()

transferEncoding [STRING|FIELD]

See Mail::Message::Body::transferEncoding()

type

See Mail::Message::Body::type()

Access to the Payload

file

See Mail::Message::Body::file()

lines

See Mail::Message::Body::lines()

string

See Mail::Message::Body::string()

Constructing a Body

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 MailBox?

attach MESSAGES, OPTIONS

See Mail::Message::Body::Construct::attach()

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.

concatenate COMPONENTS

See Mail::Message::Body::Construct::concatenate()

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               DEFAULT
charset              undef
mime_type            undef
result_type          <same as source>
transfer_encoding    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 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
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.

foreachLine CODE

See Mail::Message::Body::Construct::foreachLine()

getTransferEncHandler TYPE

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

stripSignature OPTIONS

See Mail::Message::Body::Construct::stripSignature()

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

Reading and Writing [internals]

AUTOLOAD

See Mail::Message::Body::AUTOLOAD()

fileLocation [BEGIN,END]

See Mail::Message::Body::fileLocation()

load

See Mail::Message::Body::load()

moveLocation [DISTANCE]

See Mail::Message::Body::moveLocation()

read PARSER, HEAD, BODYTYPE [,CHARS [,LINES]]

See Mail::Message::Body::read()

Logging and Tracing

defaultTrace [LEVEL, [LEVEL]

See Mail::Reporter::defaultTrace()

errors

See Mail::Reporter::errors()

log [LEVEL [,STRINGS]]

See Mail::Reporter::log()

report [LEVEL]

See Mail::Reporter::report()

reportAll [LEVEL]

See Mail::Reporter::reportAll()

trace [LEVEL]

See Mail::Reporter::trace()

warnings

See Mail::Reporter::warnings()

Other Methods

DESTROY

See Mail::Reporter::DESTROY()

inGlobalDestruction

See Mail::Reporter::inGlobalDestruction()

logPriority LEVEL

See Mail::Reporter::logPriority()

logSettings

See Mail::Reporter::logSettings()

notImplemented

See Mail::Reporter::notImplemented()

SEE ALSO

A good start to read is Mail::Box-Overview. More documentation and a mailinglist are available from the project's website at http://perl.overmeer.net/mailbox/.

AUTHOR

Mark Overmeer (mark@overmeer.net) with the help of many.

VERSION

This code is beta, version 2.023.

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.