Mail::Message::Body::Encode(3pm)

1Mail::Message::Body::EnUcsoedre(C3o)ntributed Perl DocumMeanitla:t:iMoenssage::Body::Encode(3)
2
3
4

NAME

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

SYNOPSIS

9        my Mail::Message $msg = ...;
10        my $decoded = $msg->decoded;
11        my $encoded = $msg->encode(mime_type => 'image/gif',
12            transfer_encoding => 'base64');
13
14        my $body = $msg->body;
15        my $decoded = $body->decoded;
16        my $encoded = $body->encode(transfer_encoding => '7bit');
17

DESCRIPTION

19       Manages the message's body encodings and decodings on request of the
20       main program.  This package adds functionality to the
21       Mail::Message::Body class when the decoded() or encode() method is
22       called.
23
24       Four types of encodings are handled (in the right order)
25
26       ·   eol encoding
27
28           Various operating systems have different ideas about how to encode
29           the line termination.  UNIX uses a LF character, MacOS uses a CR,
30           and Windows uses a CR/LF combination.  Messages which are
31           transported over Internet will always use the CRLF separator.
32
33       ·   transfer encoding
34
35           Messages transmitted over Internet have to be plain ASCII.
36           Complicated characters and binary files (like images and archives)
37           must be encoded during transmission to an ASCII representation.
38
39           The implementation of the required encoders and decoders is found
40           in the Mail::Message::TransferEnc set of packages.  The related
41           manual page lists the transfer encodings which are supported.
42
43       ·   mime-type translation
44
45           NOT IMPLEMENTED YET
46
47       ·   charset conversion
48

METHODS

50   Constructing a body
51       $obj->check
52           Check the content of the body not to include illegal characters.
53           Which characters are considered illegal depends on the encoding of
54           this body.
55
56           A body is returned which is checked.  This may be the body where
57           this method is called upon, but also a new object, when serious
58           changes had to be made.  If the check could not be made, because
59           the decoder is not defined, then "undef" is returned.
60
61       $obj->encode(OPTIONS)
62           Encode (translate) a Mail::Message::Body into a different format.
63           See the DESCRIPTION above.  Options which are not specified will
64           not trigger conversions.
65
66            -Option           --Default
67             charset            PERL if text
68             mime_type          undef
69             result_type        <same as source>
70             transfer_encoding  undef
71
72           charset => CODESET|'PERL'
73             If the CODESET is explicitly specified (for instance
74             "iso-8859-10", then the data is interpreted as raw bytes (blob),
75             not as text.  However, in case of "PERL", it is considered to be
76             an internal representation of characters (either latin1 or utf8
77             (not the same as utf-8), you should not know).
78
79           mime_type => STRING|FIELD
80             Convert into the specified mime type, which can be specified as
81             STRING or FIELD.  The FIELD is a Mail::Message::Field, and the
82             STRING is converted in such object before use.
83
84           result_type => CLASS
85             The type of body to be created when the body is changed to
86             fulfill the request on re-coding.  Also the intermediate stages
87             in the translation process (if needed) will use this type. CLASS
88             must extend Mail::Message::Body.
89
90           transfer_encoding => STRING|FIELD
91       $obj->encoded
92           Encode the body to a format what is acceptable to transmit or write
93           to a folder file.  This returns the body where this method was
94           called upon when everything was already prepared, or a new encoded
95           body otherwise.  In either case, the body is checked.
96
97       $obj->unify(BODY)
98           Unify the type of the given BODY objects with the type of the
99           called body.  "undef" is returned when unification is impossible.
100           If the bodies have the same settings, the BODY object is returned
101           unchanged.
102
103           Examples:
104
105            my $bodytype = Mail::Message::Body::Lines;
106            my $html  = $bodytype->new(mime_type=>'text/html', data => []);
107            my $plain = $bodytype->new(mime_type=>'text/plain', ...);
108
109            my $unified = $html->unify($plain);
110            # $unified is the data of plain translated to html (if possible).
111
112   About the payload
113       $obj->dispositionFilename([DIRECTORY])
114           Returns the name which can be used as filename to store the
115           information in the indicated DIRECTORY. To get a filename, various
116           fields are searched for "filename" and "name" attributes.  Without
117           DIRECTORY, the name found will be returned.
118
119           Only the basename of the found name will be used, for security
120           reasons: otherwise, it may be possible to access other directories
121           than the one indicated.  If no name was found, or the name is
122           already in use, then an unique name is generated.
123
124       $obj->isBinary
125           Returns true when the un-encoded message is binary data.  This
126           information is retrieved from knowledge provided by MIME::Types.
127
128       $obj->isText
129           Returns true when the un-encoded message contains printable text.
130
131   Internals
132       $obj->addTransferEncHandler(NAME, CLASS|OBJECT)
133           Mail::Message::Body->addTransferEncHandler(NAME, CLASS|OBJECT)
134
135           Relate the NAMEd transfer encoding to an OBJECTs or object of the
136           specified CLASS.  In the latter case, an object of that CLASS will
137           be created on the moment that one is needed to do encoding or
138           decoding.
139
140           The CLASS or OBJECT must extend Mail::Message::TransferEnc.  It
141           will replace existing class and object for this NAME.
142
143           Why aren't you contributing this class to MailBox?
144
145       $obj->getTransferEncHandler(TYPE)
146           Get the transfer encoder/decoder which is able to handle TYPE, or
147           return undef if there is no such handler.
148

DIAGNOSTICS

150       Warning: Charset $name is not known
151           The encoding or decoding of a message body encounters a character
152           set which is not understood by Perl's Encode module.
153
154       Warning: No decoder defined for transfer encoding $name.
155           The data (message body) is encoded in a way which is not currently
156           understood, therefore no decoding (or recoding) can take place.
157
158       Warning: No encoder defined for transfer encoding $name.
159           The data (message body) has been decoded, but the required encoding
160           is unknown.  The decoded data is returned.
161

LICENSE

167       Copyrights 2001-2011 by Mark Overmeer. For other contributors see
168       ChangeLog.
169
170       This program is free software; you can redistribute it and/or modify it
171       under the same terms as Perl itself.  See
172       http://www.perl.com/perl/misc/Artistic.html
173
174
175
176perl v5.12.3                      2011-01-26    Mail::Message::Body::Encode(3)

NAME

SYNOPSIS

DESCRIPTION

METHODS

DIAGNOSTICS

SEE ALSO

LICENSE