1=encoding utf8
2
3=head1 NAME
4
5Mail::Message::Body::Encode - organize general message encodings
6
7=head1 SYNOPSIS
8
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
18=head1 DESCRIPTION
19
20Manages the message's body encodings and decodings on request of the
21main program.  This package adds functionality to the L<Mail::Message::Body|Mail::Message::Body>
22class when the L<decoded()|Mail::Message::Body/"Constructing a body"> or L<encode()|Mail::Message::Body::Encode/"Constructing a body"> method is called.
23
24Four types of encodings are handled (in the right order)
25
26=over 4
27
28=item * eol encoding
29
30Various operating systems have different ideas about how to encode the
31line termination.  UNIX uses a LF character, MacOS uses a CR, and
32Windows uses a CR/LF combination.  Messages which are transported over
33Internet will always use the CRLF separator.
34
35=item * transfer encoding
36
37Messages transmitted over Internet have to be plain ASCII.  Complicated
38characters and binary files (like images and archives) must be encoded
39during transmission to an ASCII representation.
40
41The implementation of the required encoders and decoders is found in
42the L<Mail::Message::TransferEnc|Mail::Message::TransferEnc> set of packages.  The related
43manual page lists the transfer encodings which are supported.
44
45=item * mime-type translation
46
47NOT IMPLEMENTED YET
48
49=item * charset conversion
50
51=back
52
53=head1 METHODS
54
55=head2 Constructing a body
56
57=over 4
58
59=item $obj-E<gt>B<check>()
60
61Check the content of the body not to include illegal characters.  Which
62characters are considered illegal depends on the encoding of this body.
63
64A body is returned which is checked.  This may be the body where this
65method is called upon, but also a new object, when serious changes had
66to be made.  If the check could not be made, because the decoder is not
67defined, then C<undef> is returned.
68
69=item $obj-E<gt>B<encode>(%options)
70
71Encode (translate) a L<Mail::Message::Body|Mail::Message::Body> into a different format.
72See the DESCRIPTION above.  Options which are not specified will not trigger
73conversions.
74
75 -Option           --Default
76  charset            PERL if text
77  mime_type          undef
78  result_type        <same as source>
79  transfer_encoding  undef
80
81=over 2
82
83=item charset => CODESET|'PERL'
84
85If the CODESET is explicitly specified (for instance C<iso-8859-10>, then
86the data is interpreted as raw bytes (blob), not as text.  However, in
87case of C<PERL>, it is considered to be an internal representation of
88characters (either latin1 or Perl's utf8 --not the same as utf-8--, you should
89not know).
90
91=item mime_type => STRING|FIELD
92
93Convert into the specified mime type, which can be specified as STRING
94or FIELD.  The FIELD is a L<Mail::Message::Field|Mail::Message::Field>, and the STRING is
95converted in such object before use.
96
97=item result_type => CLASS
98
99The type of body to be created when the body is changed to fulfill the request
100on re-coding.  Also the intermediate stages in the translation process (if
101needed) will use this type. CLASS must extend L<Mail::Message::Body|Mail::Message::Body>.
102
103=item transfer_encoding => STRING|FIELD
104
105=back
106
107=item $obj-E<gt>B<encoded>()
108
109Encode the body to a format what is acceptable to transmit or write to
110a folder file.  This returns the body where this method was called
111upon when everything was already prepared, or a new encoded body
112otherwise.  In either case, the body is checked.
113
114=item $obj-E<gt>B<unify>($body)
115
116Unify the type of the given $body objects with the type of the called
117body.  C<undef> is returned when unification is impossible.  If the
118bodies have the same settings, the $body object is returned unchanged.
119
120Examples:
121
122 my $bodytype = Mail::Message::Body::Lines;
123 my $html  = $bodytype->new(mime_type=>'text/html', data => []);
124 my $plain = $bodytype->new(mime_type=>'text/plain', ...);
125
126 my $unified = $html->unify($plain);
127 # $unified is the data of plain translated to html (if possible).
128
129=back
130
131=head2 About the payload
132
133=over 4
134
135=item $obj-E<gt>B<dispositionFilename>( [$directory] )
136
137Various fields are searched for C<filename> and C<name> attributes.  Without
138$directory, the name found will be returned unmodified.
139
140When a $directory is given, a filename is composed.  For security reasons,
141only the basename of the found name gets used and many potentially
142dangerous characters removed.  If no name was found, or when the found
143name is already in use, then an unique name is generated.
144
145Don't forget to read RFC6266 section 4.3 for the security aspects in your
146email application.
147
148=item $obj-E<gt>B<isBinary>()
149
150Returns true when the un-encoded message is binary data.  This information
151is retrieved from knowledge provided by L<MIME::Types|MIME::Types>.
152
153=item $obj-E<gt>B<isText>()
154
155Returns true when the un-encoded message contains printable
156text.
157
158=back
159
160=head2 Internals
161
162=over 4
163
164=item $obj-E<gt>B<addTransferEncHandler>( $name, <$class|$object> )
165
166=item Mail::Message::Body-E<gt>B<addTransferEncHandler>( $name, <$class|$object> )
167
168Relate the NAMEd transfer encoding to an OBJECTs or object of the specified
169$class.  In the latter case, an object of that $class will be created on the
170moment that one is needed to do encoding or decoding.
171
172The $class or $object must extend L<Mail::Message::TransferEnc|Mail::Message::TransferEnc>.  It will
173replace existing class and object for this $name.
174
175Why aren't you contributing this class to MailBox?
176
177=item $obj-E<gt>B<getTransferEncHandler>($type)
178
179Get the transfer encoder/decoder which is able to handle $type, or return
180undef if there is no such handler.
181
182=back
183
184=head1 DIAGNOSTICS
185
186=over 4
187
188=item Warning: Charset $name is not known
189
190The encoding or decoding of a message body encounters a character set which
191is not understood by Perl's Encode module.
192
193=item Warning: No decoder defined for transfer encoding $name.
194
195The data (message body) is encoded in a way which is not currently understood,
196therefore no decoding (or recoding) can take place.
197
198=item Warning: No encoder defined for transfer encoding $name.
199
200The data (message body) has been decoded, but the required encoding is
201unknown.  The decoded data is returned.
202
203=back
204
205=head1 SEE ALSO
206
207This module is part of Mail-Message distribution version 3.011,
208built on July 27, 2021. Website: F<http://perl.overmeer.net/CPAN/>
209
210=head1 LICENSE
211
212Copyrights 2001-2021 by [Mark Overmeer <markov@cpan.org>]. For other contributors see ChangeLog.
213
214This program is free software; you can redistribute it and/or modify it
215under the same terms as Perl itself.
216See F<http://dev.perl.org/licenses/>
217
218