IMAP_ListMBs

4D v19

IMAP_ListMBs


IMAP_ListMBs ( imap_ID ; mbRefName ; mbName ; mbNamesArray ; mbAttribsArray ; mbHierarArray ; subscribedMB ) -> 戻り値

引数	型	説明
imap_ID	倍長整数	IMAPログイン参照
mbRefName	テキスト	ヌル文字またはメールボックス名またはメールボックス階層レベル
mbName	テキスト	ヌル文字またはメールボックス名またはワイルドカード
mbNamesArray	文字配列	メールボックス名配列 (パス名)
mbAttribsArray	文字配列	メールボックス属性配列
mbHierarArray	文字配列	階層区切り文字配列
subscribedMB	整数	0 = 利用可能なすべてのユーザメールボックスをリスト、1 = 購読済みメールボックスのみをリスト
戻り値	整数	エラーコード

説明

IMAP_ListMBs コマンドは、接続ユーザの利用可能なメールボックスのリストと付随する情報を返します。コマンドの実行に失敗すると、配列は初期化されます。

返されるメールボックスリストは、mbRefNameとmbName二つの引数の組み合わせによって決まるため、これら二つの引数をひとつとして考える必要があります。

subscribedMBが1の場合、返されるリストは購読済みのメールボックスに制限されます (IMAP_SubscribeMBを参照) 。

多くのメールボックスや複雑な階層のメールボックスストラクチャのスキャンを行うなどのため、IMAP_ListMBsの実行に時間がかかる場合、以下の方法をとることができます:

IMAP_ListMBsにワイルドカードを使用する (後述)
IMAP_ListMBs コマンド使用時にsubscribedMB 引数を1にして、IMAP_SubscribeMB コマンドを使用して設定したメールボックスのみをリストする

imap_ID はIMAP_Loginで作成されるIMAPログイン参照です。

mbRefName は mbName 引数とともに、検索対象のメールボックスを指定します。参照名 (mbRefName) はUnixシステムのCurrent Working Directoryとして使用されるべきです。言い換えれば、メールボックス名 (mbName) は参照名 (mbRefName) によって特定されるディレクトリ内に置かれたファイルとして解釈されます。IMAPの仕様は、参照名 (mbRefName) の解釈を"処理系に依存"としていることに注意してください。mbRefName 参照引数を使用しない動作モードをユーザに提供することを強く推奨します。そうすれば、参照引数を使用しない古いサーバと相互運用することが可能となります。

mbRefName が空の文字列なら、mbName 引数のみがメールボックスリストのために使用されます。

mbRefName がメールボックス名またはメールボックス階層レベルを含んでいる場合、この引数はmbName 引数がどのように解釈されるかを決定するために使用されます。

Note: 参照引数を使用する場合、階層区切り文字を置くことを強く推奨します。これにより、どのようなIMAPサーバが使用されていても、完全に準拠することが保障されます。

mbName は mbRefName 引数とともに使用され、mbName 引数が解釈されるコンテキストを決定します。

mbName が空の文字列の場合、階層区切り文字が返されます。

Note: mbRefName 引数を使用してbreakout facilityを実装する場合、メールボックス引数に前置階層区切り文字を使用するかしないかを、ユーザが選択できるようにすべきです。なぜならサーバにより、さらには同じサーバのメールストアにより前置階層区切り文字の処理が異なるからです。ある時は前置階層区切り文字は“参照引数の切り捨て”を意味し、またある時は二つは結合され、追加の階層区切り文字を切り捨てることを意味するからです。

mbNamesArray 配列は利用可能なメールボックスの名前を受け取ります。

mbAttribsArray 配列は利用可能なメールボックスの属性を受け取ります。

メールボックス属性

四つのメールボックス属性が定義されています:

\Noinferiors: 子レベル階層が現在存在せず、作成することもできない。
\Noselect: この名前を選択可能なメールボックスとして使用できない。
\Marked: サーバがメールボックスに“interesting”のマーク付けをしている; おそらくメールボックスには、最後に選択されてから追加されたメッセージが含まれている。
\Unmarked: メールボックスには、最後に選択されてからメッセージが追加されていない。

mbHierarArray 配列には、利用可能なメールボックスの階層区切り文字が返されます。

階層区切り文字は、メールボックス名中の階層レベルを区切るために使用される文字です。この文字を使用して子メールボックスを作成したり、上位レベルや下位レベルを検索したりできます。トップレベルのすべての子ノードは同じ区切り文字を使用します。

subscribedMB は購読済みのメールボックスのみをリストするかどうか指定するために使用します。0を渡すと利用可能なすべてのユーザメールボックスがリストされます。1を渡すと購読済みのメールボックスがリストされます。subscribedMB はオプションの引数で、指定しない場合のデフォルト値は0です。

例題 1

以下の例では:

IMAP_ListMBs(imap_ID;"4DIC/Work/";"Test";mbNamesArray;mbAttribsArray;mbHierarArray)

“4DIC/Work/Test”から利用可能なすべてのメールボックスが返されます。

IMAPサーバが意図されたとおり解釈を行わない場合、mbRefNameを使用せず、mbRefNameとmbName の値を結合して、mbNameに渡してください:

IMAP_ListMBs(imap_ID;"";"4DIC/Work/Test";mbNamesArray;mbAttribsArray;mbHierarArray)

例題 2

以下の例は:

IMAP_ListMBs(imap_ID;"";"";mbNamesArray;mbAttribsArray;mbHierarArray)

階層区切り文字を返します。

ワイルドカード文字を使用する

mbRefNameとmbName引数にワイルドカード文字を使用して、メールボックスの選択をより簡単にできます。カレントのワイルドカードの例を以下に示しますが、ワイルドカードの解釈はIMAPサーバにより異なることに留意してください。つまり以下の例は動作しないことがあります。その場合、お使いのIMAPサーバのワイルドカードをチェックしてください。

“ * ” はその位置の0個以上の文字にマッチします:

IMAP_ListMBs(imap_ID;"";"*";mbNamesArray;mbAttribsArray;mbHierarArray)

は接続ユーザが利用可能なすべてのメールボックスを返します。

IMAP_ListMBs(imap_ID;"";"Work*";mbNamesArray;mbAttribsArray;mbHierarArray)

はルート“Work”にマッチするすべての利用可能なメールボックスを返します。

“ % ”は“ * ”と同じものですが、階層区切り文字にマッチしない点が異なります。“%”がmbName 引数の最後の文字である場合、マッチした階層レベルも返されます。これらの階層レベルが選択不可のメールボックスである場合、\Noselect メールボックス属性が返されます (“メールボックス属性”の節を参照)。

IMAP_ListMBs(imap_ID"";"Work/%";mbNamesArray;mbAttribsArray;mbHierarArray)

は接続ユーザが利用可能な、ルート“Work”にマッチするすべてのメールボックスと、さらに一つの階層レベルが返します。

“%” はメールボックスの階層をレベルごとに解析する際に有効です。
以下のメールボックス階層がある時に:

INBOX
   MailboxA
      MailboxAA
      MailboxAB
   MailboxB
      MailboxBA
      MailboxBB
   MailboxC
      MailboxCA
      MailboxCB

IMAP_ListMBs(imap_ID;"";"%";mbNamesArray;mbAttribsArray;mbHierarArray)

は INBOX, MailboxA, MailboxB そして MailboxCを返します。

IMAP_ListMBs(imap_ID;"";"MailboxA%";mbNamesArray;mbAttribsArray;mbHierarArray)

は MailboxAA と MailboxABを返します。

このテクニックを使用して、

IMAP_ListMBs(imap_ID;"";"*";mbNamesArray;mbAttribsArray;mbHierarArray)

の回答待ちでユーザコントロールが長時間失われてしまうようなことを避けることができます。

IMAPサーバ自身が検索レベルを制限するかもしれないことに注意してください。

参照

IMAP_GetMBStatus
IMAP_SubscribeMB