ruby--ruby/doc/net/pop.rd.ja

=begin

= net/pop.rb version 1.2.3

== このライブラリについて

メールを受信するためのプロトコル POP3 (Post Office Protocol version 3) を
を扱うライブラリです。POP3 の実装は [RFC1939]
((<URL:http://www.ietf.org/rfc/rfc1939.txt>)) に基いています。

== 使用例

=== メールの受信

メールを受信してファイル 'inbox/1' 'inbox/2'... に書きこみ、
サーバ上からメールを消します。
pop3.server.address は適宜読みかえてください。

    require 'net/pop'

    Net::POP3.start( 'pop3.server.address', 110,
                     'YourAccount', 'YourPassword' ) {|pop|
      if pop.mails.empty? then
        puts 'no mail.'
      else
        i = 0
        pop.each_mail do |m|   # or "pop.mails.each ..."
          File.open( 'inbox/' + i.to_s, 'w' ) {|f|
            f.write m.pop
          }
          m.delete
          i += 1
        end
      end
      puts "#{pop.mails.size} mails popped."
    }

=== 短くする

以下は動作は同じでコードを短くしたバージョンです。

    require 'net/pop'
    Net::POP3.start( 'pop3.server.address', 110,
                     'YourAccount', 'YourPassword' ) {|pop|
      if pop.mails.empty? then
        puts 'no mail.'
      else
        i = 0
        pop.delete_all do |m|
          File.open( 'inbox/' + i.to_s, 'w' ) {|f|
            f.write m.pop
          }
          i += 1
        end
      end
    }

クラスメソッドの POP3.delete_all を使うとさらに短くなります。

    require 'net/pop'
    i = 0
    Net::POP3.delete_all( 'pop3.server.address', 110,
                          'YourAccount', 'YourPassword' ) do |m|
      File.open( 'inbox/' + i.to_s, 'w' ) {|f|
        f.write m.pop
      }
      i += 1
    end

=== ファイルに直接書く

これまでの例では m.pop の部分でメールをひとつの文字列として
うけとっていましたが、たとえば 3MB くらいある巨大なメールの場合は
これではまずい場合があります。そのような場合は以下のように m.pop
に File オブジェクトを与える手が使えます。

    require 'net/pop'
    Net::POP3.delete_all( 'pop3.server.address', 110,
                          'YourAccount', 'YourPassword' ) do |m|
      File.open( 'inbox', 'w' ) {|f|
        m.pop f   ####
      }
    end

=== APOP

APOP 認証を使うには
(1) POP3 クラスのかわりに APOP クラスを使う
(2) POP3.start の第五引数に true を渡す
の二通りの方法があります。

    # (1)
    require 'net/pop'
    Net::APOP.start( 'apop.server.address', 110,
                     'YourAccount', 'YourPassword' ) {|pop|
      # Rest code is same.
    }

    # (2)
    require 'net/pop'
    Net::POP3.start( 'apop.server.address', 110,
                     'YourAccount', 'YourPassword',
                     true   ####
    ) {|pop|
      # Rest code is same.
    }

== Net::POP3 class

=== クラスメソッド

: new( address = 'localhost', port = 110, apop = false )
    Net::POP3 オブジェクトを生成します。まだ接続はしません。
    apop が真のときは APOP 認証を行うオブジェクトを生成します。

: start( address = 'localhost', port = 110, account, password )
: start( address = 'localhost', port = 110, account, password ) {|pop| .... }
    address の port 番ポートに接続し、アカウント account パスワード
    password で POP ログインします。第二引数 port に nil を渡すと
    POP3 のデフォルトポート(110)を使います。

        Net::POP3.start( addr, port, account, password ) do |pop|
          pop.each_mail do |m|
            file.write m.pop
            m.delete
          end
        end

: foreach( address = 'localhost', port = 110, account, password ) {|mail| .... }
    POP セッションを開き、サーバ上のすべてのメールに対して繰り返します。
    以下と同じです。

        Net::POP3.start( address, port, account, password ) {|pop|
          pop.each_mail do |m|
            yield m
          end
        }

        # example
        Net::POP3.foreach( 'your.pop.server', 110,
                           'YourAccount', 'YourPassword' ) do |m|
          file.write m.pop
          m.delete if $DELETE
        end

: delete_all( address = 'localhost', port = 110, account, password )
: delete_all( address = 'localhost', port = 110, account, password ) {|mail| .... }
    POP セッションを開き、サーバ上のメールをすべて削除します。
    ブロックが与えられた時は削除する前にブロックにそのメールを
    渡します。以下と同じです。

        # example
        Net::POP3.delete_all( addr, nil, 'YourAccount', 'YourPassword' ) do |m|
          m.pop file
        end

: auth_only( address = 'localhost', port = 110, account, password )
    POP セッションを開き認証だけを行って接続を切ります。
    POP before SMTP 専用です。

        # example
        pop = Net::POP3.auth_only( 'your.pop3.server',
                                    nil,     # using default (110)
                                   'YourAccount',
                                   'YourPassword' )

=== メソッド

: start( account, password )
: start( account, password ) {|pop| .... }
    リモートホストとの接続を開始し、アカウントに account、
    パスワードに password を使って POP ログインします。

: active?
    POP3 セッションが開始されていたら真。

: address
    接続するアドレス

: port
    接続するポート番号

: open_timeout
: open_timeout=(n)
    接続時に待つ最大秒数。この秒数たってもコネクションが
    開かなければ例外 TimeoutError を発生します。

: read_timeout
: read_timeout=(n)
    読みこみ (read(1) 一回) でブロックしてよい最大秒数。
    この秒数たっても読みこめなければ例外 TimeoutError を発生します。

: finish
    POP3 セッションを終了します。セッション開始前にこのメソッドが
    呼ばれた場合は例外 IOError を発生します。

: mails
    Net::POPMail オブジェクトの配列をかえします。
    この配列はセッションを開始したときに自動的に更新されます。

: each_mail {|popmail| .... }
: each {|popmail| .... }
    pop3.mails.each と同じです。

: delete_all
: delete_all {|popmail| .... }
    サーバ上のメールを全て消去します。
    ブロックを与えられたときは消去する前にその POPMail オブジェクトを
    ブロックに渡します。

        # example
        n = 1
        pop.delete_all do |m|
          File.open("inbox/#{n}") {|f| f.write m.pop }
          n += 1
        end

: auth_only( account, password )
    POP セッションを開き認証だけを行って接続を切ります。
    POP before SMTP 専用です。
        # example
        pop = Net::POP3.new( 'your.pop3.server' )
        pop.auth_only 'YourAccount', 'YourPassword'

: reset
    セッションをリセットします。
    具体的には POPMail#delete で消したメールが全て復活します。
    (POP3 ではメール一個だけを復活する方法はありません)

== Net::APOP

このクラスでは新しいメソッドは導入していません。
認証方式が APOP に変わるだけです。

=== スーパークラス
Net::POP3

== Net::POPMail

POP サーバー上のメール一通を抽象的に表現するクラス。
メールの取得や消去といった操作をカプセル化します。

=== メソッド

: pop( dest = '' )
    メールを受信して dest に << メソッドを使って書きこみます。
    dest を返します。

        # example
        allmails = nil
        POP3.start( 'your.pop3.server', 110,
                    'YourAccount, 'YourPassword' ) do |pop|
          allmails = pop.mails.collect {|popmail| popmail.pop }
        end

: pop {|str| .... }
    メールの文字列を少しづつ読みこみ、順次ブロックに与えます。

        # example
        POP3.start( 'localhost', 110 ) {|pop3|
          pop3.each_mail do |m|
            m.pop do |str|
              # do anything
            end
          end
        }

: header
    ヘッダだけを受信して文字列で返します。

: top( lines )
    メールヘッダと lines 行ぶんの本文を取得し文字列で返します。

: delete
    サーバ上からメールを削除します。

: size
    メールのサイズ (単位はバイト) をかえします。

: deleted?
    メールがサーバ上で消去されているとき真。消去してしまったら
    POP3#reset を使う以外に復活する方法はありません。

=end