* doc/net/smtp.rd.ja: add note for RubyMail/TMail.

git-svn-id: svn+ssh://ci.ruby-lang.org/ruby/trunk@2641 b2dd03c8-39d4-4d8f-98ff-823fe69b080e

doc/net/smtp.rd.ja

@@ -0,0 +1,205 @@
+=begin
+
+= net/smtp.rb
+
+== このライブラリについて
+
+メールを送信するためのプロトコル SMTP (Simple Mail Transfer Protocol)
+を扱うライブラリです。ヘッダなどメールのデータを扱うことはできません。
+SMTP の実装は RFC2821 に基いています。
+
+  * RFC2821 ((<URL:http://www.ietf.org/rfc/rfc2821.txt>))
+
+== メールの編集について
+
+このライブラリができるのは送信だけです。メールヘッダの編集機能などは
+ありません。高度な編集機能が必要なら、TMail や RubyMail のような
+ライブラリを併用してください。いずれも RAA からダウンロードできます。
+またインターネットメールフォーマットの正式な規格書は RFC2822 です。
+
+  * RAA ((<URL:http://www.ruby-lang.org/en/raa.html>))
+  * RFC2822 ((<URL:http://www.ietf.org/rfc/rfc2822.txt>))
+
+== 使用例
+
+=== とにかくメールを送る
+
+SMTP を使ってメールを送るにはまず SMTP.start でセッションを開きます。
+第一引数がサーバのアドレスで第二引数がポート番号です。
+ブロックを使うと File.open と同じように終端処理を自動的にやってくれる
+のでおすすめです。
+
+    require 'net/smtp'
+    Net::SMTP.start( 'your.smtp.server', 25 ) {|smtp|
+        # use smtp object only in this block
+    }
+
+your.smtp.server は適切な SMTP サーバのアドレスに読みかえてください。
+通常は LAN の管理者やプロバイダが SMTP サーバを用意してくれているはずです。
+
+セッションが開いたらあとは send_mail でメールを流しこむだけです。
+
+    require 'net/smtp'
+
+    Net::SMTP.start( 'your.smtp.server', 25 ) {|smtp|
+        smtp.send_mail <<EndOfMail, 'your@mail.address', 'to@some.domain'
+    From: Your Name <your@mail.address>
+    To: Dest Address <to@some.domain>
+    Subject: test mail
+    Date: Sat, 23 Jun 2001 16:26:43 +0900
+    Message-Id: <unique.message.id.string@some.domain>
+
+    This is test mail.
+    EndOfMail
+    }
+
+=== セッションを終了する
+
+メールを送ったら SMTP#finish を呼んでセッションを終了しなければいけ
+ません。File のように GC 時に勝手に close されることもありません。
+いろいろなところで finish がないソースコードの例を見掛けますが、
+すべて誤りです。finish は必ず呼んでください。
+
+またブロック付きの SMTP.start/SMTP#start を使うと勝手に finish を
+呼んでくれるので便利です。可能な限りブロック付きの start を使うのが
+よいでしょう。
+
+    # using SMTP#finish
+    smtp = Net::SMTP.start( 'your.smtp.server', 25 )
+    smtp.send_mail mail_string, 'from@address', 'to@address'
+    smtp.finish
+
+    # using block form of SMTP.start
+    Net::SMTP.start( 'your.smtp.server', 25 ) {|smtp|
+        smtp.send_mail mail_string, 'from@address', 'to@address'
+    }
+
+=== 文字列以外からの送信
+
+ひとつ上の例では文字列リテラル(ヒアドキュメント)を使って送信しましたが、
+each メソッドを持ったオブジェクトからならなんでも送ることができます。
+以下は File オブジェクトから直接送信する例です。
+
+    require 'net/smtp'
+    Net::SMTP.start( 'your.smtp.server', 25 ) {|smtp|
+        File.open( 'Mail/draft/1' ) {|f|
+            smtp.send_mail f, 'your@mail.address', 'to@some.domain'
+        }
+    }
+
+=== HELO ドメイン
+
+SMTP ではメールを送る側のホストの名前 (HELO ドメインと呼ぶ) を要求
+されるのですが、Net::SMTP ではとりあえず localhost.localdomain と
+いう名前を送信しています。たいていの SMTP サーバはこの HELO ドメイン
+による認証はあまり真面目に行わないので (簡単に偽造できるからです)
+問題にならないことが多いのですが、まれにメールセッションを切られる
+こともあります。そういうときはとりあえず HELO ドメインを与えてみて
+ください。もちろんそれ以外の時も HELO ドメインはちゃんと渡すのが
+ベストです。
+
+HELO ドメインは SMTP.start/SMTP#start の第三引数 helo_domain に指定
+します。
+
+    Net::SMTP.start( 'your.smtp.server', 25,
+                     'mail.from.domain' ) {|smtp|
+
+よくあるダイヤルアップホストの場合、HELO ドメインには ISP のメール
+サーバのドメインを使っておけばたいてい通ります。
+
+== class Net::SMTP
+
+=== クラスメソッド
+
+: new( address, port = 25 )
+    新しい SMTP オブジェクトを生成します。address はSMTPサーバーのFQDNで、
+    port は接続するポート番号です。ただし、このメソッドではまだ接続はしません。
+
+: start( address, port = 25, helo_domain = 'localhost.localdomain', account = nil, password = nil, authtype = nil )
+: start( address, port = 25, helo_domain = 'localhost.localdomain', account = nil, password = nil, authtype = nil ) {|smtp| .... }
+    以下と同じです。
+        Net::SMTP.new(address,port).start(helo_domain,account,password,authtype)
+
+        # example
+        Net::SMTP.start( 'your.smtp.server' ) {
+            smtp.send_mail mail_string, 'from@mail.address', 'dest@mail.address'
+        }
+
+=== メソッド
+
+: start( helo_domain = <local host name>, account = nil, password = nil, authtype = nil )
+: start( helo_domain = <local host name>, account = nil, password = nil, authtype = nil ) {|smtp| .... }
+    TCP コネクションを張り、同時に SMTP セッションを開始します。そのとき、
+    こちらのホストの FQDN を helo_domain に指定します。
+    もしすでにセッションが開始していたら IOError を発生します。
+
+    account と password の両方が与えられた場合、AUTH コマンドによって
+    認証を行います。authtype は使用する認証のタイプで、シンボル
+    で :plain か :cram_md5 を指定します。
+
+: active?
+    SMTP セッションが開始されていたら真。
+
+: address
+    接続するアドレス
+
+: port
+    接続するポート番号
+
+: open_timeout
+: open_timeout=(n)
+    接続時に待つ最大秒数。この秒数たってもコネクションが
+    開かなければ例外 TimeoutError を発生します。
+
+: read_timeout
+: read_timeout=(n)
+    読みこみ (read(1) 一回) でブロックしてよい最大秒数。
+    この秒数たっても読みこめなければ例外 TimeoutError を発生します。
+
+: finish
+    SMTP セッションを終了します。セッション開始前にこのメソッドが
+    呼ばれた場合は例外 IOError を発生します。
+
+: send_mail( mailsrc, from_addr, *to_addrs )
+    mailsrc をメールとして送信します。mailsrc は each イテレータを持つ
+    オブジェクトならなんでも構いません (たとえば String や File)。
+    from_domain は送り主のメールアドレス ('...@...'のかたちのもの) で、
+    to_addrs には送信先メールアドレスを並べます。
+
+        # example
+        Net::SMTP.start( 'your.smtp.server' ) {|smtp|
+            smtp.send_mail mail_string,
+                           'from@mail.address',
+                           'dest@mail.address' 'dest2@mail.address'
+        }
+
+: ready( from_addr, *to_addrs ) {|adapter| .... }
+    メール書きこみの準備をしたうえで、write メソッドを持つオブジェクトを
+    ブロックにあたえます。from_addr は送信元メールアドレスで to_addrs は
+    宛先のメールボックスです。
+
+        # example
+        Net::SMTP.start( 'your.smtp.server', 25 ) {|smtp|
+	    smtp.ready( 'from@mail.addr', 'dest@mail.addr' ) {|f|
+                f.puts 'From: aamine@loveruby.net'
+                f.puts 'To: someone@somedomain.org'
+                f.puts 'Subject: test mail'
+                f.puts
+                f.puts 'This is test mail.'
+	    }
+        }
+
+== 発生する例外
+
+セッション中に (SMTP レベルの) エラーがおこった場合、
+以下の例外が発生します。
+: Net::ProtoSyntaxError
+    SMTP コマンドの構文ミス(500番台)
+: Net::ProtoFatalError
+    恒久的なエラー(550番台)
+: Net::ProtoUnknownError
+    予期しないエラー。おそらくバグ
+: Net::ProtoServerBusy
+    一時的なエラー(420/450番台)
+
+=end