##
1 IMAP4 オブジェクト

全ての IMAP4rev1 命令は、同じ名前のメソッドで表されており、大文字の ものも小文字のものもあります。

命令に対する引数は全て文字列に変換されます。例外は "`AUTHENTICATE`"の引数と "`APPEND`" の最後の引数で、これは IMAP4 リテラルとして 渡されます。必要に応じて (IMAP4 プロトコルが感知対象としている 文字が文字列に入っており、かつ丸括弧か二重引用符で囲われていなかった 場合) 文字列はクオートされます。しかし、"`LOGIN`" 命令の password 引数は常にクオートされます。文字列がクオートされない ようにしたい (例えば "`STORE`" 命令の flags 引数) 場合、 文字列を丸括弧で囲んでください (例: `r'(\Deleted)'`)。

各命令はタプル: `(type, [data, ...])` を返し、 type は通常 `'OK'` または `'NO'` です。 data は命令に対する応答をテキストにしたものか、命令に対する 実行結果です。各 data は文字列かタプルとなります。タプルの場合、 最初の要素はレスポンスのヘッダで、次の要素にはデータが格納されます。 (ie: 'literal' value)

以下のコマンドにおける message_set オプションは、操作の対象とな るひとつあるいは複数のメッセージを指す文字列です。単一のメッセージ番号 (`'1'`) かメッセージ番号の範囲 (`'2:4'`)、あるいは連続してい ないメッセージをカンマでつなげたもの (`'1:3,6:9'`) となります。範 囲指定でアスタリスクを使用すると、上限を無限とすることができます (`'3:*'`)。

`IMAP4` のインスタンスは以下のメソッドを持っています:

`append`( | mailbox, flags, date_time, message)

  指定された名前のメイルボックスに message を追加します。

`authenticate`( | mechanism, authobject)

  認証命令です -- 応答の処理が必要です。

  mechanismは利用する認証メカニズムを与えます。 認証メカニズムはインスタンス変数`capabilities` の中に `AUTH=mechanism`という形式で現れる必要があります。

  authobjectは呼び出し可能なオブジェクトである必要があります。

      data = authobject(response)

  これはサーバで継続応答を処理するためによばれます。 これは(おそらく)暗号化されて、サーバへ送られた `data` を返します。 もしクライアントが中断応答 "`*`" を送信した場合にはこれは `None` を返します。

`check`( | )

  サーバ上のメイルボックスにチェックポイントを設定します。 Checkpoint mailbox on server.

`close`( | )

  現在選択されているメイルボックスを閉じます。削除されたメッセージは 書き込み可能メイルボックスから除去されます。"`LOGOUT`" 前に 実行することを勧めます。

`copy`( | message_set, new_mailbox)

  message_set で指定したメッセージ群を new_mailbox の 末尾にコピーします。

`create`( | mailbox)

  mailbox と名づけられた新たなメイルボックスを生成します。

`delete`( | mailbox)

  mailbox と名づけられた古いメイルボックスを削除します。

`deleteacl`( | mailbox, who)

  mailbox における who についてのACLを削除(権限を削除)します。 バージョン 2.4 で 新たに追加 された仕様です。

`expunge`( | )

  選択されたメイルボックスから削除された要素を永久に除去します。 各々の削除されたメッセージに対して、"`EXPUNGE`" 応答を 生成します。返されるデータには "`EXPUNGE`" メッセージ番号を 受信した順番に並べたリストが入っています。

`fetch`( | message_set, message_parts)

  メッセージ (の一部) を取りよせます。message_parts はメッセージパートの名前を表す文字列を丸括弧で囲ったもので、 例えば: "`"(UID BODY[TEXT])"`" のようになります。 返されるデータはメッセージパートのエンベロープ情報とデータ からなるタプルです。

`getacl`( | mailbox)

  mailbox に対する "`ACL`" を取得します。 このメソッドは非標準ですが、 "`Cyrus`" サーバでサポートされています。

`getannotation`( | mailbox, entry, attribute)

  mailbox に対する "`ANNOTATION`" を取得します。 このメソッドは非標準ですが、 "`Cyrus`" サーバでサポートされています。 バージョン 2.5 で 新たに追加 された仕様です。

`getquota`( | root)

  "`quota`" root により、リソース使用状況と制限値を取得します。 このメソッドは RFC 2087 で定義されている IMAP4 QUOTA 拡張の一部です。 バージョン 2.3 で 新たに追加 された仕様です。

`getquotaroot`( | mailbox)

  mailbox に対して "`quota`" root を実行した結果のリストを 取得します。 このメソッドは RFC 2087 で定義されている IMAP4 QUOTA 拡張の一部です。 バージョン 2.3 で 新たに追加 された仕様です。

`list`( | [directory[, pattern]])

  pattern にマッチする directoryメイルボックス名を列挙します。 directory の標準の設定値は最上レベルのメイルフォルダで、 pattern は標準の設定では全てにマッチします。返されるデータには "`LIST`" 応答のリストが入っています。

`login`( | user, password)

  平文パスワードを使ってクライアントを照合します。 password はクオートされます。

`login_cram_md5`( | user, password)

  パスワードの保護のため、クライアント認証時に"`CRAM-MD5`"だけを使用します。 これは、"`CAPABILITY`"レスポンスに "`AUTH=CRAM-MD5`" が含まれる場合のみ 有効です。 バージョン 2.3 で 新たに追加 された仕様です。

`logout`( | )

  サーバへの接続を遮断します。サーバからの "`BYE`" 応答を返します。

`lsub`( | [directory[, pattern]])

  購読しているメイルボックス名のうち、ディレクトリ内でパターンにマッチ するものを列挙します。 directory の標準の設定値は最上レベルのメイルフォルダで、 pattern は標準の設定では全てにマッチします。返されるデータには 返されるデータはメッセージパートエンベロープ情報とデータからなるタプルです。

`myrights`( | mailbox)

  mailboxにおける自分のACLを返します。(すなわち自分がmailboxで持って いる権限を返します。) バージョン 2.4 で 新たに追加 された仕様です。

`namespace`( | )

  RFC2342で定義されるIMAP名前空間を返します。 バージョン 2.3 で 新たに追加 された仕様です。

`noop`( | )

  サーバに "`NOOP`" を送信します。

`open`( | host, port)

  host 上の port に対するソケットを開きます。 このメソッドで確立された接続オブジェクトは `read`、 `readline`、`send`、および`shutdown` メソッドで 使われます。このメソッドはオーバライドすることができます。

`partial`( | message_num, message_part, start, length)

  メッセージの後略された部分を取り寄せます。 返されるデータはメッセージパートエンベロープ情報とデータからなるタプルです。

`proxyauth`( | user)

  userとして認証されたものとします。 認証された管理者がユーザの代理としてメイルボックスにアクセス する際に使用します。 バージョン 2.3 で 新たに追加 された仕様です。

`read`( | size)

  遠隔のサーバから size バイト読み出します。 このメソッドはオーバライドすることができます。

`readline`( | )

  遠隔のサーバから一行読み出します。 このメソッドはオーバライドすることができます。

`recent`( | )

  サーバに更新を促します。新たなメッセージがない場合応答は `None` になり、そうでない場合 "`RECENT`" 応答の値になります。

`rename`( | oldmailbox, newmailbox)

  oldmailbox という名前のメイルボックスを newmailbox に名称変更します。

`response`( | code)

  応答 code を受信していれば、そのデータを返し、そうでなければ `None` を返します。通常の形式 (usual type) ではなく指定したコード を返します。

`search`( | charset, criterion[, ...])

  条件に合致するメッセージをメイルボックスから検索します。 charset は `None` でもよく、この場合にはサーバ への要求内に "`CHARSET`" は指定されません。IMAP プロトコルは 少なくとも一つの条件 (criterion) が指定されるよう要求しています; サーバがエラーを返した場合、例外が送出されます。

  例:

      # M is a connected IMAP4 instance...
      typ, msgnums = M.search(None, 'FROM', '"LDJ"')

      # or:
      typ, msgnums = M.search(None, '(FROM "LDJ")')

`select`( | [mailbox[, readonly]])

  メイルボックスを選択します。返されるデータは mailbox 内の メッセージ数 ("`EXISTS`" 応答) です。標準の設定では mailbox は `'INBOX'` です。readonly が設定された 場合、メイルボックスに対する変更はできません。

`send`( | data)

  遠隔のサーバに `data` を送信します。 このメソッドはオーバライドすることができます。

`setacl`( | mailbox, who, what)

  "`ACL`" を mailbox に設定します。 このメソッドは非標準ですが、 "`Cyrus`" サーバでサポートされています。

`setannotation`( | mailbox, entry, attribute[, ...])

  "`ANNOTATION`" を mailbox に設定します。 このメソッドは非標準ですが、 "`Cyrus`" サーバでサポートされています。 バージョン 2.5 で 新たに追加 された仕様です。

`setquota`( | root, limits)

  "`quota`" root のリソースを limits に設定します。 このメソッドは RFC 2087 で定義されている IMAP4 QUOTA 拡張の一部です。 バージョン 2.3 で 新たに追加 された仕様です。

`shutdown`( | )

  `open` で確立された接続を閉じます。 このメソッドはオーバライドすることができます。

`socket`( | )

  サーバへの接続に使われているソケットインスタンスを返します。

`sort`( | sort_criteria, charset, search_criterion[, ...])

  `sort` 命令は `search` に結果の並べ替え (sort) 機能をつけた 変種です。返されるデータには、条件に合致するメッセージ番号をスペースで 分割したリストが入っています。 sort 命令は search_criterium の前に二つの引数を持ちます; sort_criteria のリストを丸括弧で囲ったものと、検索時の charset です。 `search` と違って、検索時の charset は必須です。 `uid sort` 命令もあり、`search` に対する `uid search` と同じように `sort` 命令に対応します。 `sort` 命令はまず、charset 引数の指定に従って searching criteria の文字列を解釈し、メイルボックスから与えられた検索条件に合致する メッセージを探します。次に、合致したメッセージの数を返します。

  "`IMAP4rev1`" 拡張命令です。

`status`( | mailbox, names)

  mailbox の指定ステータス名の状態情報を要求します。

`store`( | message_set, command, flag_list)

  メイルボックス内のメッセージ群のフラグ設定を変更します。 command は RFC 2060 のセクション 6.4.6 で指定されているもので、 "FLAGS", "+FLAGS", あるいは "-FLAGS" のいずれかとなります。オプション で末尾に ".SILENT" がつくこともあります。

  たとえば、すべてのメッセージに削除フラグを設定するには次のようにします。

      typ, data = M.search(None, 'ALL')
      for num in data[0].split():
         M.store(num, '+FLAGS', '\\Deleted')
      M.expunge()

`subscribe`( | mailbox)

  新たなメイルボックスを購読 (subscribe) します。

`thread`( | threading_algorithm, charset, search_criterion[, ...])

  `thread`コマンドは`search`にスレッドの概念を加えた変形版で ス。返されるデータは空白で区切られたスレッドメンバのリストを含んでい ます。

  各スレッドメンバは0以上のメッセージ番号からなり、空白で区切られ て おり、親子関係を示しています。

  `thread`コマンドはsearch_criterion引数の前に2つの引数を持っています。 threading_algorithmとcharsetです。 `search`コマンドとは違い、charsetは必須です。 `search`に対する `uid search`と同様に、 `thread`にも `uid thread`があります。

  `thread`コマンドはまずメールボックス中のメッセージを、charsetを 用いた検索条件で検索します。その後マッチしたメッセージを指定された スレッドアルゴリズムでスレッド化して返します.

  これは "`IMAP4rev1`" の拡張コマンドです。 バージョン 2.4 で 新たに追加 された仕様です。

`uid`( | command, arg[, ...])

  command args を、メッセージ番号ではなく UID で指定されたメッセージ群に 対して実行します。命令内容に応じた応答を返します。少なくとも 一つの引数を与えなくてはなりません; 何も与えない場合、サーバは エラーを返し、例外が送出されます。

`unsubscribe`( | mailbox)

  古いメイルボックスの購読を解除 (unsubscribe) します。

`xatom`( | name[, arg[, ...]])

  サーバから "`CAPABILITY`" 応答で通知された単純な拡張命令を 許容 (allow) します。

`IMAP4_SSL` のインスタンスは追加のメソッドを一つだけ持ちます:

`ssl`( | )

  サーバへの安全な接続に使われる SSLObject インスタンスを返します。

以下の属性が `IMAP4` のインスタンス上で定義されています:

`PROTOCOL_VERSION`
  サーバから返された "`CAPABILITY`" 応答にある、サポートされている 最新のプロトコルです。

`debug`
  デバッグ出力を制御するための整数値です。初期値はモジュール変数 `Debug` から取られます。3 以上の値にすると各命令をトレースします。