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