<!--
   $FML: Message.sgml,v 1.5 2010/03/18 20:28:05 fukachan Exp $
-->

<chapter id="module.mail.message">
	<title>
	Mail::Message モジュール
	</title>

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

<para>
Mail::Message クラスはメールの解析と、
解析されたデータ構造へのさまざまな操作手段を提供します。
</para>

<para>
もう少し詳しく説明すると、このモジュールはメールを解析し、
<screen>
(multipart でない場合)

header -> body

(multipart の場合)

header -> preamble -> part1 -> part2 -> trailor
</screen>
のようにオブジェクトが数珠つなぎとなったデータ構造を作ります。ちなみに
鎖と鎖の間は double link list です。Mail::Message のクラスはこのような
データ構造に対して、さまざまな操作を行なうメソッドを提供しています。
</para>

<para>
この鎖の部分部分それぞれが Mail::Message オブジェクトです。つまり一通
のメールはメールヘッダから始まるオブジェクトの鎖として表現されます。
</para>

<para>
メールヘッダは Mail::Message のタイプが text/rfc822-headers で、
その data が Mail::Header オブジェクトになります。
一方 part1 は
text/plain
で、
data 部分が文字列(テキスト)へのリファレンスです。
</para>

<para>
参照:
<ulink url="../../en/modules/Mail/Message.txt">
Mail::Message モジュールのマニュアル(英語)
</ulink>
</para>

</sect1>


<sect1 id="module.mail.message.parse">
	<title>
	Mail::Message モジュール: 解析する
	</title>

<para>
parse() メソッドは引数で与えられたファイル(名)かファイルディスクリプタ
に対しメッセージの解析を試みます。
</para>

<para>
data_type_list() は鎖の列の情報を返します。情報は ARRAY REFERENCE の形
で返されます。たとえば MIME/Multipart は次のように表現されています
(ちなみに、以下の表示はデバッグモードで出力されるものです)。
<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>
真中の列が各オブジェクトの種別を表しています。
右端はメール全体の mime type です。
</para>

</sect1>


<sect1 id="module.mail.message.create">
	<title>
	Mail::Message モジュール: 新しいメッセージを作る
	</title>

<para>
new() メソッドは通常、新しいメッセージを作る際に使われます。
</para>

<para>
MIME/multipart 作成専用のメソッドもあります。
<screen>
build_mime_multipart_chain($args)
parse_and_build_mime_multipart_chain($args)
build_mime_header($args)
</screen>
注意: これらのメソッドを直接呼び出すことは実際ないので、
将来、これらは private methods に移行するかもしれません。
これらのメソッドは使わないでください。
</para>

<para>
実際のところ MIME/mulitpart の作成には
Mail::Message::Compose クラスを使っています。
実のところ、このクラスの実態は CPAN の MIME::Lite そのものです :-)
</para>

</sect1>


<sect1 id="module.mail.message.headerop">
	<title>
	Mail::Message モジュール: ヘッダの操作
	</title>

<para>
dup_header() メソッドは
RFC822 型メッセージのヘッダ部分のみをコピーします。
メール本体の部分はそのままです。
複製されたヘッダオブジェクトからのリンクは
メールの本体です。
<screen>
$header1 = $message0->dup_header0;

              |<--------------- メール本体 ------------->
$header0 ---> part1 -> part2 -> ...
                A
                |
$header1 ------+
</screen>
</para>


<para>
whole_message_header() 
メソッドはメッセージ中の「ヘッダ部分のオブジェクト」を返します。
「文字列ではない」ことに注意して下さい。
</para>

<para>
__head_message() は鎖の先頭のオブジェクトを返します。
__last_message() は鎖の最後のオブジェクトを返します。
モジュールの中で使われていますが、
これらはプライベート・メソッドなので、
これらのメソッドは使わないで下さい。
将来、これらのコードは消去します。
なお __head_message() は、
通常、図の header オブジェクトを返すことになりますので、
多くの場合 whole_message_header() と等価です。
</para>

<para>
header_data_type()
メソッドはメール全体のタイプ(文字列)を返します。
つまり、このメッセージは単なるテキストなのかマルチパートなのか？
などの情報を教える関数です。
</para>

</sect1>


<sect1 id="module.mail.message.bodyop">
	<title>
	Mail::Message モジュール: メッセージ本文の操作
	</title>

<para>
本節では、次のようなオブジェクトの鎖を例にとることにします。
<screen>
(multipart でない場合)

header -> body

(multipart の場合)

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

<para>
(一部、前述の繰り返しになります)。
</para>

<para>
header_data_type()
メソッドはメール全体のタイプ(文字列)を返します。
つまり、header の Content-Type で得られる情報です。
</para>

<para>
whole_message_body() メソッドは
body ないしは part1 の部分のオブジェクトを返します。
whole_message_body_head() メソッドも同じ返り値です。
</para>

<para>
__head_message() は鎖の先頭のオブジェクトを返します。
__last_message() は鎖の最後のオブジェクトを返します。
そのため、通常、図の header オブジェクトを返すことになりますので、
多くの場合 whole_message_header() と等価です。
__last_message() は鎖の最後の部分なのでメッセージ本文の最後になります。
</para>

<para>
find_first_plaintext_message($args)
は
鎖の中で最初の plain/text タイプの Mail::Message オブジェクトを返します。
フィルタリングでは最初の
plain/text タイプのメッセージ部分に着目することが多いので
この関数を使うと便利です。
</para>

</sect1>


<sect1 id="module.mail.message.search">
	<title>
	Mail::Message モジュール: オブジェクトの検索
	</title>

<para>
find() メソッドは Mail::Message オブジェクトの特定のタイプを探し、
最初に見つけたオブジェクトを返します。
ヘッダの Content-Type: ではありません。
注意。
</para>

</sect1>


<sect1 id="module.mail.message.print">
	<title>
	Mail::Message モジュール: メッセージを表示する。
	</title>

<para>
print() メソッドは文字どおり print です。
通常は引数で出力するファイルディスクリプタを渡して下さい。
</para>

<para>
print() には CRLF なのか LF なのかを指定する mode という概念があります。
このために
set_print_mode(mode) および
reset_print_mode()
というメソッドがあります。
通常は raw で、SMTP の時だけは smtp を指定して下さい。
</para>

</sect1>


<sect1 id="module.mail.message.utils">
	<title>
	Mail::Message モジュール: 便利な関数
	</title>

<sect2>
	<title>
	サイズ
	</title>

<para>
size()
は(鎖の一つ一つの Mail::Message)オブジェクトのサイズを返します。
メール全体ではありません。注意。
header_size()
や
body_size()
を使うと、ヘッダやメール本文全体の長さを教えてくれます。
</para>

<para>
is_empty()
はオブジェクトのデータが空かどうかを教えてくれます。
</para>

<para>
これらはフィルタリングで有用です。
</para>

</sect2>


<sect2>
	<title>
	一般的な情報
	</title>

<para>
envelope_sender()
はメールの送信者情報(文字列)を返します。
文字通り、いわゆる Envelope Sender 情報です。
</para>

<para>
data_type()
メソッドは
Mail::Message オブジェクトのタイプ(文字列)を返します。
これは、メール全体のタイプ（マルチパートとか text/plain)ではなく、
鎖の各部分のオブジェクト・タイプであることに注意して下さい。
</para>

<para>
encoding_mechanism()
メソッドは
Mail::Message オブジェクトのエンコーディングメカニズム(文字列)を返します。
エンコーディングされていない場合 undef が返ります。
これは、メール全体のタイプ（マルチパートとか text/plain)ではなく、
鎖の各部分のオブジェクト・タイプであることに注意して下さい。
</para>

</sect2>


<sect2>
	<title>
	Mail::Message オブジェクト内部の構造を知る
	</title>

<para>
num_paragraph()
メソッドは、
その Mail::Message オブジェクトの中に
何個のパラグラフがあるか(数字)を返します。
</para>


<para>
nth_paragraph(数字)
メソッドは
「数字」番目のパラグラフの内容を文字列として返します。
たとえば、一番目のパラグラフは 0 ではなく 1 と指定して下さい。
ここは、わざとＣ言語風ではなく人間に分かりやすいように
「 1から始まる仕様」としてあります。
</para>


<para>
header()
メソッドは
MIME/multipart の各ブロックにあるヘッダ部分を返します。
data()
メソッドは、データの部分です。
それぞれ
message_fields($size)
および
message_text($size)
メソッドの alias になっています。
</para>

</sect2>

</sect1>


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

<para>

<ulink url="../../en/modules/Mail/Message.txt">
Mail::Message モジュールマニュアル(英語)
</ulink>
</para>
</sect1>


</chapter>
