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 Perl's
77             utf8 --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           Various fields are searched for "filename" and "name" attributes.
115           Without $directory, the name found will be returned unmodified.
116
117           When a $directory is given, a filename is composed.  For security
118           reasons, only the basename of the found name gets used and many
119           potentially dangerous characters removed.  If no name was found, or
120           when the found name is already in use, then an unique name is
121           generated.
122
123           Don't forget to read RFC6266 section 4.3 for the security aspects
124           in your email application.
125
126       $obj->isBinary()
127           Returns true when the un-encoded message is binary data.  This
128           information is retrieved from knowledge provided by MIME::Types.
129
130       $obj->isText()
131           Returns true when the un-encoded message contains printable text.
132
133   Internals
134       $obj->addTransferEncHandler( $name, <$class|$object> )
135       Mail::Message::Body->addTransferEncHandler( $name, <$class|$object> )
136           Relate the NAMEd transfer encoding to an OBJECTs or object of the
137           specified $class.  In the latter case, an object of that $class
138           will be created on the moment that one is needed to do encoding or
139           decoding.
140
141           The $class or $object must extend Mail::Message::TransferEnc.  It
142           will replace existing class and object for this $name.
143
144           Why aren't you contributing this class to MailBox?
145
146       $obj->getTransferEncHandler($type)
147           Get the transfer encoder/decoder which is able to handle $type, or
148           return undef if there is no such handler.
149

DIAGNOSTICS

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

LICENSE

168       Copyrights 2001-2021 by [Mark Overmeer <markov@cpan.org>]. For other
169       contributors see ChangeLog.
170
171       This program is free software; you can redistribute it and/or modify it
172       under the same terms as Perl itself.  See http://dev.perl.org/licenses/
173
174
175
176perl v5.34.0                      2021-07-27    Mail::Message::Body::Encode(3)

NAME

SYNOPSIS

DESCRIPTION

METHODS

DIAGNOSTICS

SEE ALSO

LICENSE