yuki:imap4

yuki:imap4

IMAP4 client module

IMAP4 クライアントモジュールです。 RFC 3501(RFC 2060) の機能(クライアントコマンド)とほぼ1対1対応の API を提供する低レベル層ライブラリです。 Gauche で IMAP4 クライアントアプリケーションを作成するのにご利用頂けます。

ソースコードはこちらからダウンロードできます。モジュール名、ファイル名は適宜変更してご利用下さい。各クライアントコマンドの機能については、 RFC を参照して下さい。


Changes

2007-08-12 Gauche 0.8.10 でも動作するように string-downcase! の使用を止め string-downcase に変更しました。その他好ましくないコーディングを改めました。
2006-09-03 このページでの最初のリリース

Module: rfc.imap4

IMAP4 のクライアント機能を提供します。関数名が imap4.xxx という形式のものは RFC で定義されているコマンドと1対1対応の関係にあります。 imap4-xxx という形式のものは RFC とは(1対1には)対応しないものです。

サーバとの通信が成功しているにも関わらず、サーバが NO 応答か BAD 応答を返した場合にはそれぞれ <imap4-error-reply-no>, <imap4-error-reply-bad> クラスの例外を投げます。これらの例外が投げられた場合でも、オブジェクト内部の整合性は保たれているため、サーバとの通信を継続することができます。

サーバから予期しない応答があった場合などには、 <imap4-error> クラスの例外が投げられます。またソケット通信でその他の例外が投げられる可能性があります。これらの場合にはオブジェクト内部の整合性やサーバの状態を保証できないため、サーバとの通信を継続することは(一般には)できません。

imap4-shutdown は、サーバの応答を待たずに、強制的に通信を切断しますので、エラー発生時も含めいつでも呼び出し可能です。

Class: <imap4>

IMAP4 クライアントを表現するオブジェクトです。スレッド・アンセーフなので、同一インスタンスへの複数スレッドからのアクセスには、別途排他制御が必要です。各メソッドは失敗すると例外を投げます。

Instance Variable of <imap4>: host

IMAP4 サーバを指定します。ホスト名もしくは IP アドレスを文字列で指定します。デフォルトは "127.0.0.1" (ローカルホスト)です。

Instance Variable of <imap4>: port

IMAP4 サーバのポート番号を整数で指定します。デフォルトは 143 です。


Method: imap4-connect (imap4 <imap4>) &optional host port

サーバに接続します。 host はホスト名もしくは IP アドレスを文字列で指定します。 port はポート番号を整数で指定します。引数を省略した場合には、インスタンス作成時に指定された値を使用します。接続に成功するとサーバからの OK 応答文を返却します。

Method: imap4-disconnect (imap4 <imap4>)

サーバに LOGOUT コマンドを送信して、通信を切断します。返却値はありません。

Method: imap4-shutdown (imap4 <imap4>)

通信を強制的に切断します。 imap4-disconnect と異なり LOGOUT コマンドの送信は行いません。サーバが応答しない場合の強制切断に使用します。返却値はありません。

Method: imap4-login (imap4 <imap4>) user password mechanism

サーバにログインします。 user と password はユーザ名とパスワードを文字列で指定します。 mechanism は認証方法をシンボルで指定します。現在、サポートされている認証方法は login (プレーンテキスト)と cram-md5 (CRAM-MD5暗号)です。認証に成功すると OK 応答文を返却します。


Method: imap4.capability (imap4 <imap4>)

[RFC 2060] サーバに CAPABILITY コマンドを送信します。サポートされている機能のリストを文字列のリストとして返します。

gosh> (imap4.capability imap4)
("IMAP4REV1" "IDLE" "NAMESPACE" "MAILBOX-REFERRALS" "SCAN" "SORT" "THREAD=REFERENCES" "THREAD=ORDEREDSUBJECT" "MULTIAPPEND" "LOGIN-REFERRALS" "AUTH=CRAM-MD5" "AUTH=LOGIN")

Method: imap4.noop (imap4 <imap4>)

[RFC 2060] サーバに NOOP コマンドを送信します。返却値はありません。

Method: imap4.select (imap4 <imap4>) mailbox

[RFC 2060] サーバに SELECT コマンドを送信し、メールボックスを選択します。 mailbox は IMAP4 メールボックス名を文字列で指定します。返却値はシンボルをキーとする連想リストです。

キー
flags フラグの状態を表す文字列のリスト
exists メールボックス内に存在するメッセージ数(整数)
recent メールボックス内の \Recent フラグがセットされているメッセージ数(整数)
gosh> (imap4.select imap4 "INBOX")
((flags "\\Answered" "\\Flagged" "\\Deleted" "\\Draft" "\\Seen")
 (exists . 10)
 (recent . 2))

Method: imap4.examine (imap4 <imap4>) mailbox

[RFC 2060] サーバに EXAMINE コマンドを送信します。メールボックスを読み込み専用で選択する以外は imap4.select と同じです。

Method: imap4.create (imap4 <imap4>) mailbox

[RFC 2060] サーバに CREATE コマンドを送信し、メールボックスを作成します。返却値はありません。

Method: imap4.delete (imap4 <imap4>) mailbox

[RFC 2060] サーバに DELETE コマンドを送信し、メールボックスを削除します。返却値はありません。

Method: imap4.rename (imap4 <imap4>) existing-mailbox new-mailbox

[RFC 2060] サーバに RENAME コマンドを送信し、メールボックスの名称を変更します。 existing-mailbox と new-mailbox は既存のメールボックス名と新しいメールボックス名を表す文字列です。返却値はありません。

Method: imap4.subscribe (imap4 <imap4>) mailbox

[RFC 2060] サーバに SUBSCRIBE コマンドを送信します。返却値はありません。

Method: imap4.unsubscribe (imap4 <imap4>) mailbox

[RFC 2060] サーバに UNSUBSCRIBE コマンドを送信します。返却値はありません。

Method: imap4.list (imap4 <imap4>) reference mailbox

[RFC 2060] サーバに LIST コマンドを送信します。 reference と mailbox は文字列です。返却値はシンボルをキーとする連想リストのリストです。

キー
attributes 属性を表す文字列のリスト
delimiter メールボックス名の区切りに使用される文字列(imap4-unquote-string でアンクォート済み)
name メールボックス名を表す文字列(imap4-unquote-string でアンクォート済み)
gosh> (imap4.list imap4 "\"\"" "*")
(((attributes "\\NoInferiors") (delimiter . #f) (name . "INBOX"))
 ((attributes "\\NoInferiors" "\\UnMarked") (delimiter . "/") (name . "spam"))
 ((attributes "\\NoInferiors" "\\Marked") (delimiter . "/") (name . "friends"))
 ((attributes "\\NoInferiors" "\\UnMarked") (delimiter . "/") (name . ".procmailrc"))
 ((attributes "\\NoInferiors" "\\UnMarked") (delimiter . "/") (name . "Trash")))

Method: imap4.lsub (imap4 <imap4>) reference mailbox

[RFC 2060] imap4.list と同様に、サーバに LSUB コマンドを送信します。

Method: imap4.status (imap4 <imap4>) mailbox arg ...

[RFC 2060] サーバに STATUS コマンドを送信します。 arg は、文字列、シンボル、それらのリスト、あるいは "(item1 item2 ...)" という書式の文字列のいずれかです。各文字列/シンボルはステータス項目を表さねばなりません。返却値はシンボルをキーとする連想リストです。

キー
messages メールボックス内のメッセージ数(整数)
recent 新着メッセージ数(整数)
unseen 未読メッセージ数(整数)
uidnext 次のメッセージに付けられるユニーク ID (整数)
uidvalidity 有効なユニーク ID の最大値(整数)
gosh> (imap4.status imap4 "INBOX" '(messages recent uidnext uidvalidity unseen))
((uidvalidity . 1060866867)
 (uidnext . 57826)
 (unseen . 5)
 (recent . 2)
 (messages . 10))

Method: imap4.append (imap4 <imap4>) mailbox literal &keyword date-time flags

[RFC 2060] サーバに APPEND コマンドを送信します。 literal はメッセージを表す文字列か u8vector あるいは s8vector です。 date-time は <date> オブジェクトか RFC 3501 で定められた書式の文字列です。 flags はフラグを imap4.status コマンドの arg 引数と同じ形式で指定します。返却値はありません。

Method: imap4.check (imap4 <imap4>)

[RFC 2060] サーバに CHECK コマンドを送信します。返却値はありません。

Method: imap4.close (imap4 <imap4>)

[RFC 2060] サーバに CLOSE コマンドを送信します。返却値はありません。

Method: imap4.expunge (imap4 <imap4>)

[RFC 2060] サーバに EXPUNGE コマンドを送信します。削除したメッセージの番号(整数)のリストを返却します。返却される番号は UID ではありません。詳細については RFC 3501 を参照して下さい。

Method: imap4.search (imap4 <imap4>) arg ...

Method: imap4.uid.search (imap4 <imap4>) arg ...

[RFC 2060] サーバに SEARCH/UID SEARCH コマンドを送信します。引数 arg は RFC 3501 に従った文字列です。 imap4.search はメッセージの番号(整数)のリストを返却します。 imap4.uid.search はユニーク ID (整数)のリストを返却します。

Method: imap4.fetch (imap4 <imap4>) message-set message-items

Method: imap4.uid.fetch (imap4 <imap4>) message-set message-items

[RFC 2060] サーバに FETCH/UID FETCH コマンドを送信します。 message-set はメッセージの集合を表す文字列、整数、それらのリストのいずれかです。各要素は RFC 3501 で定められた書式の文字列か、メッセージの番号/ユニーク ID を表す整数でなければなりません。 message-items はメッセージ項目を表す文字列、シンボル、あるいはそれらのリストです。返却値はメッセージ番号/ユニーク ID をキーとする連想リストです。各値は更にシンボルをキーとする連想リストになっています。

gosh> (imap4.fetch imap4 '(1 2 3) '("RFC822.SIZE" "UID"))
((1 (rfc822.size . 5015) (uid . 1096))
 (2 (rfc822.size . 4203) (uid . 1108))
 (3 (rfc822.size . 3202) (uid . 1143)))

Method: imap4.store (imap4 <imap4>) message-set item value

Method: imap4.uid.store (imap4 <imap4>) message-set item value

[RFC 2060] サーバに STORE/UID STORE コマンドを送信します。 message-set は imap4.fetch と同じものです。 item はフラグ操作の種類を表す文字列(message data item name)です。 value はフラグを imap4.status コマンドの arg 引数と同じ形式で指定します。返却値は imap4.fetch と同じ形式です。

gosh> (imap4.store imap4 "1:*" "+FLAGS" '\Seen)
((1 (flags "\\Seen"))
 (2 (flags "\\Seen"))
 (3 (flags "\\Seen")))

Method: imap4.copy (imap4 <imap4>) message-set mailbox

Method: imap4.uid.copy (imap4 <imap4>) message-set mailbox

[RFC 2060] サーバに COPY/UID COPY コマンドを送信します。 message-set は imap4.fetch と同じものです。返却値はありません。

Method: imap4.unselect (imap4 <imap4>)

[RFC 3691] サーバに UNSELECT コマンドを送信します。返却値はありません。


Slot of <imap4>: imap4-tag-formatter

クライアントからサーバへ送信するコマンドに付けるタグを生成する関数を指定します。この関数は整数を引数に取り、文字列を返す関数でなければなりません。デフォルトは number->string です。通常はデフォルトのままで十分ですが、タグにプログラム名を含ませたい場合(e.g. "MyApp0001")などには、ユーザ定義の関数を指定します。

Slot of <imap4>: imap4-input-logger

ロギング用の関数を指定します。 <imap4> オブジェクトはサーバから応答を受信すると、応答文を引数として、この関数を呼び出します。 imap4-input-logger と imap4-output-logger を指定することで、クライアント-サーバ間のすべての通信を記録することが出来ます。

Slot of <imap4>: imap4-output-logger

imap4-input-logger と同様のロギング関数です。 <imap4> オブジェクトはサーバへ命令を送信すると、命令文を引数として、この関数を呼び出します。


Class: <imap4-error>

IMAP4 クライアントモジュール内で発生したエラーを通知する例外クラスです。ソケット I/O で発生したエラーはそのままの例外クラスで通知され、 <imap4-error> クラスに変換されることはありません。

Function: imap4-error? obj

obj が <imap4-error> クラスかそのサブクラスのインスタンスである場合、真を返却します。

Class: <imap4-error-reply-no>

サーバから NO 応答を受信したことを通知する例外クラスです。 <imap4-error> クラスのサブクラスです。

Function: imap4-error-reply-no? obj

obj が <imap4-error-reply-no> クラスかそのサブクラスのインスタンスである場合、真を返却します。

Class: <imap4-error-reply-bad>

サーバから BAD 応答を受信したことを通知する例外クラスです。 <imap4-error> クラスのサブクラスです。

Function: imap4-error-reply-bad? obj

obj が <imap4-error-reply-bad> クラスかそのサブクラスのインスタンスである場合、真を返却します。


Function: imap4-quote-string str

str をクォートした文字列を返却します。 str は文字列か #f でなければなりません。 #f は "NIL" に変換されます。文字列は全体をダブルクォーテーションで括られ、内部のバックスラッシュ、ダブルクォーテーションは、バックスラッシュでエスケープされます。

Function: imap4-unquote-string str

str をアンクォートした文字列を返却します。 str は文字列でなければなりません。大文字/小文字を区別せずに "NIL" と一致する場合には、 #f に変換されます。 str の先頭と末尾がダブルクォーテーションではない場合には、 str をそのまま返却します。クォートされた文字列の場合には、先頭と末尾のダブルクォーテーションを取り除き、バックスラッシュに続く文字がバックスラッシュかダブルクォーテーションの場合にのみバックスラッシュを一つ取り除きます。それ以外の文字がバックスラッシュに続く場合には、そのままにし、バックスラッシュを取り除くことはしません。


Last modified : 2007/08/12 13:15:38 UTC