QdmailReceiver Multibyte mail decoder & POP Client

メールヘッダーの取得

メール差出人の名前部分

$receiver には、初期設定またはPOPモード初期設定にて設定した、QdmailReceiverオブジェクトが入っているものとします。

$receiver->header( array( 'from' , 'name' ) );

メール差出人のメールアドレス

$receiver->header( array('from','mail') );

メール差出人関係の情報を一括取得

$receiver->header( array('from') ) ;
または
$receiver->header( 'from' );
でも可能

配列形式で、fromヘッダーから解析された情報が返されます。

他のヘッダーについても、同様に取り出すことができます。

• 注意点！

メールヘッダーの「名称」は、すべて「小文字」で指定してください。
Subjectは×。subjectは○です。

メール件名

$receiver->header( array('subject','name') );

メール件名関係の情報を一括取得

$receiver->header( array('subject') );
または
$receiver->header( 'subject' );
でも可能

ヘッダー情報を全部配列で取得

$receiver->header( 'ALL' );

メール本文の取得

$receiver->bodyAutoSelect();

これで、htmlメールの場合は、html部分を取得し、テキストメールの場合は、テキスト部分を取得します。
テキスト部分は以下の形でも取得できます。

$receiver->text();

この形式は、テキスト部分を取得します。htmlメールであっても、代替テキストを取得します。
代替テキストがないhtmlメールの場合は、nullとなります。

html部分の取得。

$receiver->html();

テキストメールの場合は、nullとなります。
一般的には'bodyAutoSelect'コマンドを使用したほうがいいでしょう。

添付ファイルの取得

$attach = $receiver->attach();

以下の形で、添付ファイルの配列が$attachに格納されます。

（例）
array(
    0 => array(
         'value' => '添付ファイルの中身（デコード済みのバイナリ）',
         'finename' => 'ファイル名（日本語デコード済み）',
         'finename_safe' => 'urlencode済みのファイル名',
         'content-type' => 'image/jpg',
         'enc' => 'base64',
        ),
    1 => array(
         'value' => '添付ファイルの中身（デコード済みのバイナリ）',
         'finename' => 'ファイル名（日本語デコード済み）',
         'finename_safe' => 'urlencode済みのファイル名',
         'content-type' => 'image/jpg',
         'enc' => 'base64',
         'content-id' => '........',
    ),
);

'finename'は、マルチバイト（日本語）のファイル名にデコード済みですので、そのままwindowsなどで、そのファイル名で保存しようとすると不都合がでる場合もあります。その場合は、ご自分でsjisにエンコードしてからお使いください。
（もちろん、元のファイル名がアルファベットファイル名であれば、特段の問題はでないと思います。）
'finename_safe'は、ファイル名をurlencodeしていますので、このままファイル名として保存しても、大丈夫なようにしています(windows,unix,linux)。

添付ファイルを保存するサンプルコード

$attach = $receiver->attach();
foreach($attach as $att){
    $fp=fopen($att['filename_safe'],'w');
    fputs($fp,$att['value']);
    fclose($fp);
}

メールヘッダーの取得

メール差出人の名前部分

echo qd_receive_mail( 'header' , array('from','name') );

メール差出人のメールアドレス

echo qd_receive_mail( 'header' , array('from','mail') );

メール差出人関係の情報を一括取得

$from = qd_receive_mail( 'header' , array('from') ) ;
または
$from = qd_receive_mail( 'header' , 'from' );
でも可能

$from には、配列形式で、fromヘッダーから解析された情報が代入されます。

他のヘッダーについても、同様に取り出すことができます。

• 注意点！

メールヘッダーの「名称」は、すべて「小文字」で指定してください。
Subjectは×。subjectは○です。

メール件名

$subject = qd_receive_mail( 'header' , array('subject','name') );

メール件名関係の情報を一括取得

$subject = qd_receive_mail( 'header' , array('subject') );
または
$subject = qd_receive_mail( 'header' , 'subject' );
でも可能

ヘッダー情報を全部配列で取得

$header = qd_receive_mail( 'header' , 'ALL' );

メール本文の取得

$body = qd_receive_mail( 'body' );

これで、htmlメールの場合は、html部分を取得し、テキストメールの場合は、テキスト部分を取得します。
テキスト部分は以下の形でも取得できます。

$body = qd_receive_mail( 'text' );

この形式は、テキスト部分を取得します。htmlメールであっても、代替テキストを取得します。
代替テキストがないhtmlメールの場合は、nullとなります。

html部分の取得。

$body = qd_receive_mail( 'html' );

テキストメールの場合は、nullとなります。
一般的には'body'コマンドを使用したほうがいいでしょう。

添付ファイルの取得

$attach = qd_receive_mail( 'attach' );

以下の形で、添付ファイルの配列が$attachに格納されます。

（例）
array(
    0 => array(
         'value' => '添付ファイルの中身（デコード済みのバイナリ）',
         'finename' => 'ファイル名（日本語デコード済み）',
         'finename_safe' => 'urlencode済みのファイル名',
         'content-type' => 'image/jpg',
         'enc' => 'base64',
        ),
    1 => array(
         'value' => '添付ファイルの中身（デコード済みのバイナリ）',
         'finename' => 'ファイル名（日本語デコード済み）',
         'finename_safe' => 'urlencode済みのファイル名',
         'content-type' => 'image/jpg',
         'enc' => 'base64',
         'content-id' => '........',
    ),
);

'finename'は、マルチバイト（日本語）のファイル名にデコード済みですので、そのままwindowsなどで、そのファイル名で保存しようとすると不都合がでる場合もあります。その場合は、ご自分でsjisにエンコードしてからお使いください。
（もちろん、元のファイル名がアルファベットファイル名であれば、特段の問題はでないと思います。）
'finename_safe'は、ファイル名をurlencodeしていますので、このままファイル名として保存しても、大丈夫なようにしています(windows,unix,linux)。

添付ファイルを保存するサンプルコード

$attach = qd_receive_mail( 'attach' );
foreach($attach as $att){
    $fp=fopen($att['filename_safe'],'w');
    fputs($fp,$att['value']);
    fclose($fp);
}

ヘッダー情報は、以下のような形で内部保存されています。

$this->header = array(
    'ヘッダー名（e.g Cc）'=>array(
        0 => array(
             'mail' => 'mail_0@example.com',
             'name' => 'お名前0',
             'mime' => '=?iso2022-jp?B?......?=',
        ),
        1 => array(
             'mail' => 'mail_1@example.com',
             'name' => 'お名前1',
             'mime' => '=?iso2022-jp?B?......?=',
        ),

    'ヘッダー名(e.g. subject)'=>array(
          'name' => '件名',
          'mime' => '=?iso2022-jp?B?......?=',
    ),
);

一般的に使われているPOPプロトコルには、既読・未読の管理機能はありません。
一般的にメーラー*1は、そのソフトウエア*2で独自に既読・未読管理を行っています。

QdmailReceiverで既読・未読管理を行うには？

POPサーバーの多くは、UIDという機能を有しています。
これは、「受信サーバーが付けたメール番号」です。
その形式は様々です。
例）

プロバイダorレンタルサーバー名	UIDの形式
so-net	数字5桁
ドリームネット	数字n桁.数字n桁.サーバーNumber?
ロリポップ	数字n桁.数字n桁.サーバーNumber.lolipop.jp
さくらインターネット	UID数字n桁-数字n桁

このUIDは、セッション（プロセス）が異なっても、その受信サーバー内では一意に保たれているのが通常です*3。

UIDは、QdmailReceiverの場合、「popuid」という名称のヘッダー情報として格納します*4。
これをデータベースなり、ファイル、セッション変数等に格納することで、既読・未読の管理をすることができるでしょう。

Pointer number は既読・未読管理に不向き

QdmailReceiver (及びPOPの仕様)では$receiver->pointer();*5)機能で、メールの番号付けを行います。
これは、メールを受信順に１から番号付けしてくれるものですが、しかし、これは当該セッション（プロセス）内だけで有効なものです。
メールの取得や削除には、Pointer Numberを使いますが、そのPOPプロセス内*6だけ、ということは意識しておいてください。

	継続性	範囲	サポート
PointerNumber	POPプロセス内	そのサーバー内だけ	どのPOPサーバーもOK
UID(popuid)	削除するまでは 一意に保たれる	そのサーバー内だけ	たまにサポートしてない サーバーもあるようだ*7

UIDとPointerNumberの変換

UID →　PointerNumber（ポインタは移動しません。）

$receiver -> uidToPointer( uid );
または、
qd_receive_mail( 'uidToPointer' , uid );

　PointerNumber → UID　（ポインタが移動するので注意してください。）

$receiver -> pointer( PointerNumber );
$receiver -> header( 'popuid' );
または、

qd_receive_mail( 'pointer' , PointerNumber );
qd_receive_mail( 'popuid' );

とすることで、UIDとPOINTERの変換ができます。

POPサーバー（受信サーバー）にアクセスするための初期設定が必要です。

■一般関数タイプの例）

 include_once('qdmail_receiver.php');

 $server = array(
    'protocol'=>'pop3',
    'host'=>'pop.example.com',
    'user'=>'user-id',
    'pass'=>'password',
 );

 qd_receive_mail( 'start' , $server ); 

ご自分でお使いの受信サーバーを設定してください。

'protocol'=>'pop3',

はPOPモードにするためのおまじないですので、このまま、配列の一番最初に置いておいてください。
配列のキーは、大文字小文字を区別しませんが、将来のことを考えて小文字を推奨します。
qd_receive_mailが、一般関数タイプの関数です。オブジェクト指向ではありません。
以下のように使います。

qd_receive_mail( 'コマンド' , $server )

一度、

qd_receive_mail( 'start' , $server )

で初期化すると、QdmailReceiverは、ＰＯＰと接続し、状態を覚えていますので、次回以降の操作で'start'コマンドを送ることはありません。

文字コードについて

QdmailReceiverは、返り値をすべてmb_internal_encoding()で設定された文字コードに変換して渡します。

返り値を特定の文字コードで受け取りたい場合は、次のように指定してください。

qd_receive_mail( 'start' , $server , '文字コード')

以下は、utf-8を指定した場合です。

 $server = array(
    'protocol'=>'pop3',
    'host'=>'pop.example.com',
    'user'=>'user-id',
    'pass'=>'password',
 );

 qd_receive_mail( 'start' , $server , 'utf-8' ); 

■オブジェクト指向モードでの初期化

 $server = array(
    'protocol'=>'pop3',
    'host'=>'pop.example.com',
    'user'=>'user-id',
    'pass'=>'password',
 );

$receiver = QdmailReceiver::start( 'pop' , $server);

'pop'は、POPモードにするためのおまじないです。
$receiverにはQdmailReceiverのオブジェクトが代入されます。
newを使わずに、オブジェクトを取得します。このような取得の仕方がわからない方もいるかも知れませんが、& new するのと同じと思ってください。
newで、QdmailReceiverオブジェクトを取得することもできるのですが、3つのモードの振り分け処理を自分でしなくてはならないので、上記の方法をお薦めします。