基本タイプ(OOPタイプ)

2008/05/08 未分類 spok

メールヘッダーの取得

メール差出人の名前部分
$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);
}

一般関数タイプ

2008/05/08 未分類 spok

メールヘッダーの取得

メール差出人の名前部分
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);
}

ヘッダー情報の説明

2008/05/08 未分類 spok
ヘッダー情報は、以下のような形で内部保存されています。
$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?......?=',
    ),
);

既読・未読の管理とUID機能の解説

2008/05/08 未分類 spok
一般的に使われている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)機能で、メールの番号付けを行います。
これは、メールを受信順に1から番号付けしてくれるものですが、しかし、これは当該セッション(プロセス)内だけで有効なものです。
メールの取得や削除には、Pointer Numberを使いますが、そのPOPプロセス内*6だけ、ということは意識しておいてください。
継続性範囲サポート
PointerNumberPOPプロセス内そのサーバー内だけどの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の変換ができます。

*1 : OutlookExpressをはじめBecky!や秀丸メール、その他ほとんどすべてのメーラー

*2 : クライアント

*3 : メッセージ本文が全く同じ場合は、同じUIDになってしまうサーバーもあることはあるようだ。POPのプロトコル上は、メッセージが同じであれば同じUIDを返すことになっているけれども、多くのサーバーはそれを拡張し、同じメッセージであっても異なるUIDを返す場合が多いと思う

*4 : UIDをサポートしないサーバーのため、格納しないように設定することもできる。

*5 : 又は、qd_receive_mail('pointer', ...

*6 : サーバーやPHPのプロセスではなく、POPのプロセス

*7 : お目にかかったことはないけれど。一応この機能はPOP3プロトコルのオプション扱い

POP初期設定

2008/05/08 未分類 spok
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は、POPと接続し、状態を覚えていますので、次回以降の操作で'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つのモードの振り分け処理を自分でしなくてはならないので、上記の方法をお薦めします。