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 Mail::Mes‐
21       sage::Body class when the decoded() or encode() method is called.
22
23       Four types of encodings are handled (in the right order)
24
25       * eol encoding
26           Various operating systems have different ideas about how to encode
27           the line termination.  UNIX uses a LF character, MacOS uses a CR,
28           and Windows uses a CR/LF combination.  Messages which are trans‐
29           ported over Internet will always use the CRLF separator.
30
31       * transfer encoding
32           Messages transmitted over Internet have to be plain ASCII.  Compli‐
33           cated characters and binary files (like images and archives) must
34           be encoded during transmission to an ASCII representation.
35
36           The implementation of the required encoders and decoders is found
37           in the Mail::Message::TransferEnc set of packages.  The related
38           manual page lists the transfer encodings which are supported.
39
40       * mime-type translation
41           NOT IMPLEMENTED YET
42
43       * charset conversion
44           NOT IMPLEMENTED YET
45

METHODS

47       Constructing a body
48
49       $obj->check
50
51           Check the content of the body not to include illegal characters.
52           Which characters are considered illegal depends on the encoding of
53           this body.
54
55           A body is returned which is checked.  This may be the body where
56           this method is called upon, but also a new object, when serious
57           changes had to be made.  If the check could not be made, because
58           the decoder is not defined, then "undef" is returned.
59
60       $obj->encode(OPTIONS)
61
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            undef
68            mime_type          undef
69            result_type        <same as source>
70            transfer_encoding  undef
71
72           . charset STRING
73
74           . mime_type STRING⎪FIELD
75
76               Convert into the specified mime type, which can be specified as
77               STRING or FIELD.  The FIELD is a Mail::Message::Field, and the
78               STRING is converted in such object before use.
79
80           . result_type CLASS
81
82               The type of body to be created when the body is changed to ful‐
83               fill the request on re-coding.  Also the intermediate stages in
84               the translation process (if needed) will use this type. CLASS
85               must extend Mail::Message::Body.
86
87           . transfer_encoding STRING⎪FIELD
88
89       $obj->encoded
90
91           Encode the body to a format what is acceptable to transmit or write
92           to a folder file.  This returns the body where this method was
93           called upon when everything was already prepared, or a new encoded
94           body otherwise.  In either case, the body is checked.
95
96       $obj->unify(BODY)
97
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
114       $obj->dispositionFilename([DIRECTORY])
115
116           Returns the name which can be used as filename to store the infor‐
117           mation in the indicated DIRECTORY. To get a filename, various
118           fields are searched for "filename" and "name" attributes.  Without
119           DIRECTORY, the name found will be returned.
120
121           Only the basename of the found name will be used, for security rea‐
122           sons: otherwise, it may be possible to access other directories
123           than the one indicated.  If no name was found, or the name is
124           already in use, then an unique name is generated.
125
126       $obj->isBinary
127
128           Returns true when the un-encoded message is binary data.  This
129           information is retrieved from knowledge provided by MIME::Types.
130
131       $obj->isText
132
133           Returns true when the un-encoded message contains printable text.
134
135       Internals
136
137       $obj->addTransferEncHandler(NAME, CLASS⎪OBJECT)
138
139       Mail::Message::Body->addTransferEncHandler(NAME, CLASS⎪OBJECT)
140
141           Relate the NAMEd transfer encoding to an OBJECTs or object of the
142           specified CLASS.  In the latter case, an object of that CLASS will
143           be created on the moment that one is needed to do encoding or
144           decoding.
145
146           The CLASS or OBJECT must extend Mail::Message::TransferEnc.  It
147           will replace existing class and object for this NAME.
148
149           Why aren't you contributing this class to MailBox?
150
151       $obj->getTransferEncHandler(TYPE)
152
153           Get the transfer encoder/decoder which is able to handle TYPE, or
154           return undef if there is no such handler.
155

DIAGNOSTICS

157       Warning: No decoder defined for transfer encoding $name.
158
159       The data (message body) is encoded in a way which is not currently
160       understood, therefore no decoding (or recoding) can take place.
161
162       Warning: No encoder defined for transfer encoding $name.
163
164       The data (message body) has been decoded, but the required encoding is
165       unknown.  The decoded data is returned.
166

LICENSE

172       Copyrights 2001-2007 by Mark Overmeer.For other contributors see
173       ChangeLog.
174
175       This program is free software; you can redistribute it and/or modify it
176       under the same terms as Perl itself.  See
177       http://www.perl.com/perl/misc/Artistic.html
178
179
180
181perl v5.8.8                       2007-03-25    Mail::Message::Body::Encode(3)

NAME

SYNOPSIS

DESCRIPTION

METHODS

DIAGNOSTICS

SEE ALSO

LICENSE