path: root/fml/doc/en/tutorial/module/Message.sgml

<!--
   $FML: Message.sgml,v 1.2 2003/08/03 01:47:17 fukachan Exp $
   $jaFML: Message.sgml,v 1.2 2003/04/15 14:51:42 fukachan Exp $
-->

<chapter id="module.mail.message">
	<title>
	Mail::Message Module
	</title>

<sect1 id="module.mail.message.overview">
	<title>
	Mail::Message Overview
	</title>

<para>
Mail::Message object provides several methods to analyze a message and
manipulate messages or parts of a message.
</para>

<para>
Precisely speaking, this module analyzes the specified mail message
and build a chain of Mail::Message objects.
<screen>
If not multipart

   header -> body

else if multipart

   header -> preamble -> part1 -> part2 -> ... -> trailor
</screen>
The link between objects is double link list. Mail::Message class
provides several methods to manipulate these structures.
</para>

<para>
Each part of this chain is a Mail::Message object. In other words, one
mail message consits of a chain of plural Mail::Message objects in
&fml8; internal.
</para>

<para>
For example, "header" is a Mail::Message, which type is
text/rfc822-headers and the data is stored as Mail::Header
object. Instead "part1" is a Mail::Message object, which type is
text/plain and the data is reference to the message string.
</para>

<para>
References:
<ulink url="../../en/modules/Mail/Message.txt">
Mail::Message module manual.
</ulink>
</para>

</sect1>


<sect1 id="module.mail.message.parse">
	<title>
	Mail::Message Module: Analyze
	</title>

<para>
parse() analyzes the file. The argument is the file name or the file
handle for the file which should be specified at the argument.
</para>

<para>
data_type_list() returns information of the chain.
The return value is array reference.
For example, MIME/multipart consists of the following objects.
<screen>
  type[ 1]: text/rfc822-headers       | multipart/mixed
  type[ 2]: multipart/mixed           | multipart/mixed
  type[ 3]: multipart.preamble        | multipart/mixed
  type[ 4]: multipart.delimiter       | multipart/mixed
  type[ 5]: text/plain                | multipart/mixed
  type[ 6]: multipart.delimiter       | multipart/mixed
  type[ 7]: image/gif                 | multipart/mixed
  type[ 8]: multipart.close-delimiter | multipart/mixed
  type[ 9]: text/plain                | multipart/mixed
</screen>
The center row is the object type, the right one is the mime type of
the whole message (content-type in the mail header).
</para>

</sect1>


<sect1 id="module.mail.message.create">
	<title>
	Mail::Message Module: Create A New Object
	</title>

<para>
new() method is used to create a new object chain.
</para>

<para>
The following MIME/multipart specific methdos exist.
<screen>
build_mime_multipart_chain($args)
parse_and_build_mime_multipart_chain($args)
build_mime_header($args)
</screen>
These methods are used internally now.
So these will become private methods in the furure.
Please do not use these methods.
</para>

<para>
To create a new MIME/mulitpart message, use Mail::Message::Compose. It
is MIME::Lite class in fact :-)
</para>

</sect1>


<sect1 id="module.mail.message.headerop">
	<title>
	Mail::Message Module: Header Manipulations
	</title>

<para>
dup_header() method duplicates only header part of a chain and left
the body part as it is. The new chain has different head (header
object) but others begining from the second part is same as the
original chain.
<screen>
              |<--------------- mail body ------------->
header0 ----> part1 -> part2 -> ...
               A
               |
dup_header0 ---
</screen>
</para>


<para>
whole_message_header() returns the header object of the chain. The
return value is a Mail::Message object not string.
</para>

<para>
header_data_type() returns the type of the whole message as string.
It tells whether this message is text or multipart.
</para>

</sect1>


<sect1 id="module.mail.message.bodyop">
	<title>
	Mail::Message Module: Manipulate Messabe Body
	</title>

<para>
Consider the following object chain.
<screen>
If not multipart

header -> body

else if multipart

header -> preamble -> part1 -> part2 -> ... -> trailor
</screen>
</para>


<para>
header_data_type() return the type of the whole type.
It is known from Content-Type: in the whole message header.
</para>

<para>
whole_message_body() returns body or part1 if multipart.
whole_message_body_head() is same.
</para>

<para>
find_first_plaintext_message($args) return the first text/plain type
object in the chain. This is useful in filter codes since filter
system checks the first text field in a lot of cases.
</para>

</sect1>


<sect1 id="module.mail.message.search">
	<title>
	Mail::Message Module: Search
	</title>

<para>
find() searches the specified type of Mail::Message in the object
chain and returns the first matched object.
</para>

</sect1>


<sect1 id="module.mail.message.print">
	<title>
	Mail::Message Module: Print
	</title>

<para>
print() method is usual print() function. Usually specify the file
descriptor as an argument.
</para>

<para>
print() has the concept "mode" to specify CRLF or LF. use
set_print_mode(mode) and reset_print_mode() to set the mode. By
default, mode is raw. Specify smtp mode in using print() within SMTP
codes.
</para>

</sect1>


<sect1 id="module.mail.message.utils">
	<title>
	Mail::Message Module: Utility Functions
	</title>

<sect2>
	<title>
	Size
	</title>

<para>
size() returns the size of the object not the whole message size.
<!--
header_size() tells the size of the header.
body_size() tells the size of the body part.
-->
</para>

<para>
is_empty() tells the object data is empty or not. 
</para>
</sect2>


<sect2>
	<title>
	General Information
	</title>

<para>
envelope_sender() returns the envelope sender as string.
</para>

<para>
data_type() returns the type of the object (a part of an object chain)
not the whole message type (Content-Type: in the whole message
header).
</para>

<para>
encoding_mechanism() returns the encoding mechanism of the object (a
part of an object chain) as string. This is not of the whole message
encoding mechanism.
</para>

</sect2>


<sect2>
	<title>
	Mail::Message Internals
	</title>

<para>
num_paragraph() returns the number of paragraphs in the data of the
object.
</para>


<para>
nth_paragraph(N) returns N-th paragrah as the string.
Caution that N starts from 1 not 0.
</para>


<para>
header() returns the header part of a multipart block (header part of
an object). data() returns the data part (data part of an object).
Respectively, alias of message_fields($size) and message_text($size).
</para>

</sect2>

</sect1>


<sect1 id="module.mail.message.ref">
	<title>
	References
	</title>

<para>

<ulink url="../../en/modules/Mail/Message.txt">
Mail::Message manual
</ulink>
</para>
</sect1>


</chapter>