1Mail::Message::Body::EnUcsoedre(C3o)ntributed Perl DocumMeanitla:t:iMoenssage::Body::Encode(3)
2
6 Mail::Message::Body::Encode - organize general message encodings
7
9 my Mail::Message $msg = ...;
10 my $decoded = $msg->decoded;
11 my $encoded = $msg->encode(mime_type => 'image/gif',
12 transfer_encoding => 'base64');
13 my $body = $msg->body;
15 my $decoded = $body->decoded;
16 my $encoded = $body->encode(transfer_encoding => '7bit');
17
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 Four types of encodings are handled (in the right order)
25 • eol encoding
27 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 • transfer encoding
34 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 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 • mime-type translation
44 NOT IMPLEMENTED YET
46 • charset conversion
48
50 Constructing a body
51 $obj->charsetDetect(%options)
52 [3.013] This is tricky. It is hard to detect whether the body
53 originates from the program, or from an external source. And what
54 about a database database? are those octets or strings? Please
55 read "Autodetection of character-set" in Mail::Message::Body.
56 -Option --Default
58 external <false>
59 external => BOOLEAN
61 Do only consider externally valid character-sets, implicitly:
62 "PERL" is not an acceptable answer.
63 Mail::Message::Body->charsetDetectAlgorithm( [CODE|undef|METHOD] )
65 [3.013] When a body object does not specify its character-set, but
66 that detail is required, then it gets autodetected. The default
67 algorithm is implemented in charsetDetect(). You may change this
68 default algorithm, or pass option "charset_detect" for each call to
69 encode().
70 When you call this method with an explicit "undef", you reset the
72 default. (Without parameter) the current algorithm (CODE or method
73 name) is returned.
74 $obj->check()
76 Check the content of the body not to include illegal characters.
77 Which characters are considered illegal depends on the encoding of
78 this body.
79 A body is returned which is checked. This may be the body where
81 this method is called upon, but also a new object, when serious
82 changes had to be made. If the check could not be made, because
83 the decoder is not defined, then "undef" is returned.
84 $obj->encode(%options)
86 Encode (translate) a Mail::Message::Body into a different format.
87 See the DESCRIPTION above. Options which are not specified will
88 not trigger conversions.
89 -Option --Default
91 charset PERL
92 charset_detect <built-in>
93 mime_type undef
94 result_type <same as source>
95 transfer_encoding undef
96 charset => CHARSET|'PERL'
98 Only applies when the mime_type is textual.
99 If the CHARSET is explicitly specified (for instance
101 "iso-8859-10", then the data is being interpreted as raw bytes
102 (blob), not as text. However, in case of "PERL", it is
103 considered to be an internal representation of characters (either
104 latin1 or Perl's utf8 --not the same as utf-8--, you should not
105 want to know).
106 This setting overrules the charset attribute in the mime_type
108 FIELD.
109 charset_detect => CODE
111 [3.013] When the body does not contain an explicit charset
112 specification, then the RFC says it is "us-ascii". In reality,
113 this is not true: it is just an unknown character set. This often
114 happens when text files are included as attachment, for instance
115 a footer attachment.
116 When you want to be smarter than the default charset detector,
118 you can provide your own function for this parameter. The
119 function will get the transfer-decoded version of this body. You
120 can change the default globally via charsetDetectAlgorithm().
121 mime_type => STRING|FIELD
123 Convert into the specified mime type, which can be specified as
124 STRING or FIELD. The FIELD is a Mail::Message::Field-object,
125 representing a "Content-Type" mime header. The STRING must be
126 valid content for such header, and will be converted into a FIELD
127 object.
128 The FIELD may contain attributes. Usually, it has a "charset"
130 attribute, which explains the CHARSET of the content after
131 content transfer decoding. The "charset" option will update/add
132 this attribute. Otherwise (hopefully in rare cases) the CHARSET
133 will be auto-detected when the body gets decoded.
134 result_type => CLASS
136 The type of body to be created when the body is changed to
137 fulfill the request on re-coding. Also the intermediate stages
138 in the translation process (if needed) will use this type. CLASS
139 must extend Mail::Message::Body.
140 transfer_encoding => STRING|FIELD
142 $obj->encoded(%options)
143 Encode the body to a format what is acceptable to transmit or write
144 to a folder file. This returns the body where this method was
145 called upon when everything was already prepared, or a new encoded
146 body otherwise. In either case, the body is checked.
147 -Option --Default
149 charset_detect <the default>
150 charset_detect => CODE
152 See charsetDetectAlgorithm().
153 $obj->unify($body)
155 Unify the type of the given $body objects with the type of the
156 called body. "undef" is returned when unification is impossible.
157 If the bodies have the same settings, the $body object is returned
158 unchanged.
159 Examples:
161 my $bodytype = Mail::Message::Body::Lines;
163 my $html = $bodytype->new(mime_type=>'text/html', data => []);
164 my $plain = $bodytype->new(mime_type=>'text/plain', ...);
165 my $unified = $html->unify($plain);
167 # $unified is the data of plain translated to html (if possible).
168 About the payload
170 $obj->dispositionFilename( [$directory] )
171 Various fields are searched for "filename" and "name" attributes.
172 Without $directory, the name found will be returned unmodified.
173 When a $directory is given, a filename is composed. For security
175 reasons, only the basename of the found name gets used and many
176 potentially dangerous characters removed. If no name was found, or
177 when the found name is already in use, then an unique name is
178 generated.
179 Don't forget to read RFC6266 section 4.3 for the security aspects
181 in your email application.
182 $obj->isBinary()
184 Returns true when the un-encoded message is binary data. This
185 information is retrieved from knowledge provided by MIME::Types.
186 $obj->isText()
188 Returns true when the un-encoded message contains printable text.
189 Internals
191 $obj->addTransferEncHandler( $name, <$class|$object> )
192 Mail::Message::Body->addTransferEncHandler( $name, <$class|$object> )
193 Relate the NAMEd transfer encoding to an OBJECTs or object of the
194 specified $class. In the latter case, an object of that $class
195 will be created on the moment that one is needed to do encoding or
196 decoding.
197 The $class or $object must extend Mail::Message::TransferEnc. It
199 will replace existing class and object for this $name.
200 Why aren't you contributing this class to MailBox?
202 $obj->getTransferEncHandler($type)
204 Get the transfer encoder/decoder which is able to handle $type, or
205 return undef if there is no such handler.
206
208 Warning: Charset $name is not known
209 The encoding or decoding of a message body encounters a character
210 set which is not understood by Perl's Encode module.
211 Warning: No decoder defined for transfer encoding $name.
213 The data (message body) is encoded in a way which is not currently
214 understood, therefore no decoding (or recoding) can take place.
215 Warning: No encoder defined for transfer encoding $name.
217 The data (message body) has been decoded, but the required encoding
218 is unknown. The decoded data is returned.
219
221 This module is part of Mail-Message distribution version 3.013, built
222 on June 24, 2023. Website: http://perl.overmeer.net/CPAN/
223
225 Copyrights 2001-2023 by [Mark Overmeer <markov@cpan.org>]. For other
226 contributors see ChangeLog.
227 This program is free software; you can redistribute it and/or modify it
229 under the same terms as Perl itself. See http://dev.perl.org/licenses/
230perl v5.38.0 2023-07-20 Mail::Message::Body::Encode(3)