Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
Mail::Message::Body::EUsereContributed Perl DocuMail::Message::Body::Encode(3)

NAME
       Mail::Message::Body::Encode - organize general message encodings

SYNOPSIS
	my Mail::Message $msg =	...;
	my $decoded = $msg->decoded;
	my $encoded = $msg->encode(mime_type =>	'image/gif',
	    transfer_encoding => 'base64');

	my $body = $msg->body;
	my $decoded = $body->decoded;
	my $encoded = $body->encode(transfer_encoding => '7bit');

DESCRIPTION
       Manages the message's body encodings and	decodings on request of	the
       main program.  This package adds	functionality to the
       Mail::Message::Body class when the decoded() or encode()	method is
       called.

       Four types of encodings are handled (in the right order)

       o   eol encoding

	   Various operating systems have different ideas about	how to encode
	   the line termination.  UNIX uses a LF character, MacOS uses a CR,
	   and Windows uses a CR/LF combination.  Messages which are
	   transported over Internet will always use the CRLF separator.

       o   transfer encoding

	   Messages transmitted	over Internet have to be plain ASCII.
	   Complicated characters and binary files (like images	and archives)
	   must	be encoded during transmission to an ASCII representation.

	   The implementation of the required encoders and decoders is found
	   in the Mail::Message::TransferEnc set of packages.  The related
	   manual page lists the transfer encodings which are supported.

       o   mime-type translation

	   NOT IMPLEMENTED YET

       o   charset conversion

METHODS
   Constructing	a body
       $obj->check()
	   Check the content of	the body not to	include	illegal	characters.
	   Which characters are	considered illegal depends on the encoding of
	   this	body.

	   A body is returned which is checked.	 This may be the body where
	   this	method is called upon, but also	a new object, when serious
	   changes had to be made.  If the check could not be made, because
	   the decoder is not defined, then "undef" is returned.

       $obj->encode(OPTIONS)
	   Encode (translate) a	Mail::Message::Body into a different format.
	   See the DESCRIPTION above.  Options which are not specified will
	   not trigger conversions.

	    -Option	      --Default
	     charset		PERL if	text
	     mime_type		undef
	     result_type	<same as source>
	     transfer_encoding	undef

	   charset => CODESET|'PERL'
	     If	the CODESET is explicitly specified (for instance
	     "iso-8859-10", then the data is interpreted as raw	bytes (blob),
	     not as text.  However, in case of "PERL", it is considered	to be
	     an	internal representation	of characters (either latin1 or	Perl's
	     utf8 --not	the same as utf-8--, you should	not know).

	   mime_type =>	STRING|FIELD
	     Convert into the specified	mime type, which can be	specified as
	     STRING or FIELD.  The FIELD is a Mail::Message::Field, and	the
	     STRING is converted in such object	before use.

	   result_type => CLASS
	     The type of body to be created when the body is changed to
	     fulfill the request on re-coding.	Also the intermediate stages
	     in	the translation	process	(if needed) will use this type.	CLASS
	     must extend Mail::Message::Body.

	   transfer_encoding =>	STRING|FIELD
       $obj->encoded()
	   Encode the body to a	format what is acceptable to transmit or write
	   to a	folder file.  This returns the body where this method was
	   called upon when everything was already prepared, or	a new encoded
	   body	otherwise.  In either case, the	body is	checked.

       $obj->unify(BODY)
	   Unify the type of the given BODY objects with the type of the
	   called body.	 "undef" is returned when unification is impossible.
	   If the bodies have the same settings, the BODY object is returned
	   unchanged.

	   Examples:

	    my $bodytype = Mail::Message::Body::Lines;
	    my $html  =	$bodytype->new(mime_type=>'text/html', data => []);
	    my $plain =	$bodytype->new(mime_type=>'text/plain',	...);

	    my $unified	= $html->unify($plain);
	    # $unified is the data of plain translated to html (if possible).

   About the payload
       $obj->dispositionFilename([DIRECTORY])
	   Returns the name which can be used as filename to store the
	   information in the indicated	DIRECTORY. To get a filename, various
	   fields are searched for "filename" and "name" attributes.  Without
	   DIRECTORY, the name found will be returned.

	   Only	the basename of	the found name will be used, for security
	   reasons: otherwise, it may be possible to access other directories
	   than	the one	indicated.  If no name was found, or the name is
	   already in use, then	an unique name is generated.

       $obj->isBinary()
	   Returns true	when the un-encoded message is binary data.  This
	   information is retrieved from knowledge provided by MIME::Types.

       $obj->isText()
	   Returns true	when the un-encoded message contains printable text.

   Internals
       $obj->addTransferEncHandler(NAME, CLASS|OBJECT)
       Mail::Message::Body->addTransferEncHandler(NAME,	CLASS|OBJECT)
	   Relate the NAMEd transfer encoding to an OBJECTs or object of the
	   specified CLASS.  In	the latter case, an object of that CLASS will
	   be created on the moment that one is	needed to do encoding or
	   decoding.

	   The CLASS or	OBJECT must extend Mail::Message::TransferEnc.	It
	   will	replace	existing class and object for this NAME.

	   Why aren't you contributing this class to MailBox?

       $obj->getTransferEncHandler(TYPE)
	   Get the transfer encoder/decoder which is able to handle TYPE, or
	   return undef	if there is no such handler.

DIAGNOSTICS
       Warning:	Charset	$name is not known
	   The encoding	or decoding of a message body encounters a character
	   set which is	not understood by Perl's Encode	module.

       Warning:	No decoder defined for transfer	encoding $name.
	   The data (message body) is encoded in a way which is	not currently
	   understood, therefore no decoding (or recoding) can take place.

       Warning:	No encoder defined for transfer	encoding $name.
	   The data (message body) has been decoded, but the required encoding
	   is unknown.	The decoded data is returned.

SEE ALSO
       This module is part of Mail-Box distribution version 2.109, built on
       August 19, 2013.	Website: http://perl.overmeer.net/mailbox/

LICENSE
       Copyrights 2001-2013 by [Mark Overmeer].	For other contributors see
       ChangeLog.

       This program is free software; you can redistribute it and/or modify it
       under the same terms as Perl itself.  See
       http://www.perl.com/perl/misc/Artistic.html

perl v5.24.1			  2013-08-19	Mail::Message::Body::Encode(3)

NAME | SYNOPSIS | DESCRIPTION | METHODS | DIAGNOSTICS | SEE ALSO | LICENSE

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=Mail::Message::Body::Encode&sektion=3&manpath=FreeBSD+12.1-RELEASE+and+Ports>

home | help