зеркало из https://github.com/github/ruby.git
* doc/net/protocol.rd.ja, smtp.rd.ja, pop.rd.ja: removed.
* MANIFEST: remove doc/net/* entries. git-svn-id: svn+ssh://ci.ruby-lang.org/ruby/trunk@2289 b2dd03c8-39d4-4d8f-98ff-823fe69b080e
This commit is contained in:
aamine
Родитель
ce0de3f67b
Коммит
04168e7e3e
|
|
@ -1,3 +1,9 @@
|
|||
Tue Mar 26 20:25:28 2002 Minero Aoki <aamine@loveruby.net>
|
||||
|
||||
* doc/net/protocol.rd.ja, smtp.rd.ja, pop.rd.ja: removed.
|
||||
|
||||
* MANIFEST: remove doc/net/* entries.
|
||||
|
||||
Tue Mar 26 18:45:15 2002 WATANABE Hirofumi <eban@ruby-lang.org>
|
||||
|
||||
* configure.in (FILE_READPTR): check bufread instead of bufend
|
||||
|
|
|
|||
|
|
@ -1,433 +0,0 @@
|
|||
=begin
|
||||
|
||||
= net/http.rb
|
||||
|
||||
== このライブラリについて
|
||||
|
||||
汎用データ転送プロトコル HTTP を扱うライブラリです。
|
||||
実装は [RFC2616] ((<URL:http://www.ietf.org/rfc/rfc2616.txt>)) に
|
||||
基いています。
|
||||
|
||||
== 使用例
|
||||
|
||||
=== ウェブサーバからドキュメントを得る (GET)
|
||||
|
||||
require 'net/http'
|
||||
Net::HTTP.start( 'some.www.server', 80 ) {|http|
|
||||
response , = http.get('/index.html')
|
||||
puts response.body
|
||||
}
|
||||
|
||||
また以下は同じ意味で短く書いたものです。
|
||||
|
||||
require 'net/http'
|
||||
Net::HTTP.get_print 'some.www.server', '/index.html'
|
||||
|
||||
=== フォームの情報を送信する (POST)
|
||||
|
||||
require 'net/http'
|
||||
Net::HTTP.start( 'some.www.server', 80 ) {|http|
|
||||
response , = http.post( '/cgi-bin/any.rhtml',
|
||||
'querytype=subject&target=ruby' )
|
||||
}
|
||||
|
||||
=== プロクシ経由のアクセス
|
||||
|
||||
Net::HTTP のクラスメソッド Net::HTTP.Proxy は、常にプロクシ経由で
|
||||
接続するような動作をする、新しいクラスを作成して返します。このクラスは
|
||||
Net::HTTP を継承しているので Net::HTTP と全く同じように使えます。
|
||||
|
||||
require 'net/http'
|
||||
|
||||
$proxy_addr = 'your.proxy.addr'
|
||||
$proxy_port = 8080
|
||||
:
|
||||
Net::HTTP::Proxy($proxy_addr, $proxy_port).start( 'some.www.server' ) {|http|
|
||||
# always connect to your.proxy.addr:8080
|
||||
:
|
||||
}
|
||||
|
||||
また Net::HTTP.Proxy は第一引数が nil だと Net::HTTP 自身を返すので
|
||||
上のコードのように書いておけばプロクシなしの場合にも対応できます。
|
||||
|
||||
=== リダイレクトに対応する
|
||||
|
||||
require 'net/http'
|
||||
Net::HTTP.version_1_1
|
||||
|
||||
host = 'www.ruby-lang.org'
|
||||
path = '/'
|
||||
begin
|
||||
Net::HTTP.start( host, 80 ) {|http|
|
||||
response , = http.get(path)
|
||||
print response.body
|
||||
}
|
||||
rescue Net::ProtoRetriableError => err
|
||||
if m = %r<http://([^/]+)>.match( err.response['location'] ) then
|
||||
host = m[1].strip
|
||||
path = m.post_match
|
||||
retry
|
||||
end
|
||||
end
|
||||
|
||||
この例では URL からホスト名を得るのにいいかげんな方法を使っていますが、
|
||||
将来 URI クラスが標準添付になればもっと簡単になるはずです。
|
||||
|
||||
=== Basic 認証
|
||||
|
||||
require 'net/http'
|
||||
|
||||
Net::HTTP.start( 'auth.some.domain' ) {|http|
|
||||
response , = http.get( '/need-auth.cgi',
|
||||
'Authorization' => 'Basic ' + ["#{account}:#{password}"].pack('m').strip )
|
||||
print response.body
|
||||
}
|
||||
|
||||
バージョン 1.2 (Ruby 1.7 以降に添付) では次のように書けます。
|
||||
|
||||
require 'net/http'
|
||||
|
||||
req = Net::HTTP::Get.new('/need-auth.cgi')
|
||||
req.basic_auth 'account', 'password'
|
||||
Net::HTTP.start( 'auth.some.domain' ) {|http|
|
||||
response = http.request(req)
|
||||
print response.body
|
||||
}
|
||||
|
||||
== 新しい仕様への変更と移行措置について
|
||||
|
||||
Ruby 1.6 に入っているのが http.rb 1.1 で 1.7 以降が 1.2 ですが、
|
||||
この間ではかなり大きく仕様が変わります。そこで突然に仕様を変更
|
||||
するのでなく、両方の実装を並存させる時期を設けることにしました。
|
||||
|
||||
メソッド HTTP.version_1_2、HTTP.version_1_1 を呼ぶと
|
||||
そのあとに生成される Net::HTTP オブジェクトはそれぞれの
|
||||
バージョンの仕様で動作するようになります。以下は使用例です。
|
||||
|
||||
# example
|
||||
Net::HTTP.start {|http1| ...(http1 has 1.2 features)... }
|
||||
|
||||
Net::HTTP.version_1_1
|
||||
Net::HTTP.start {|http2| ...(http2 has 1.1 features)... }
|
||||
|
||||
Net::HTTP.version_1_2
|
||||
Net::HTTP.start {|http3| ...(http3 has 1.2 features)... }
|
||||
|
||||
この機能はスレッドセーフではありません。
|
||||
|
||||
== class Net::HTTP
|
||||
|
||||
=== クラスメソッド
|
||||
|
||||
: new( address, port = 80, proxy_addr = nil, proxy_port = nil )
|
||||
新しい HTTP オブジェクトを生成します。address は HTTP サーバーの FQDN で、
|
||||
port は接続するポート番号です。このメソッドではまだ接続はしません。
|
||||
|
||||
proxy_addr を与えるとプロクシを介して接続するオブジェクトを生成します。
|
||||
|
||||
: start( address, port = 80, proxy_addr = nil, proxy_port = nil )
|
||||
: start( address, port = 80, proxy_addr = nil, proxy_port = nil ) {|http| .... }
|
||||
以下と同じです。
|
||||
|
||||
Net::HTTP.new(address, port, proxy_addr, proxy_port).start(&block)
|
||||
|
||||
: get( address, path, port = 80 )
|
||||
ホスト address の port 番ポートに接続して path の表現する
|
||||
エンティティを取得、文字列で返します。
|
||||
|
||||
: get_print( address, path, port = 80 )
|
||||
ホスト address の port 番ポートに接続して path の表現する
|
||||
エンティティを取得したうえ、$stdout に << で出力します。
|
||||
|
||||
: Proxy( address, port = 80 )
|
||||
常に指定されたプロクシに接続するクラスを作成し返します。
|
||||
このクラスは Net::HTTP を継承しているので Net::HTTP と全く
|
||||
同じように使えます。
|
||||
|
||||
address が nil のときは Net::HTTP クラスをそのまま返します。
|
||||
|
||||
# example
|
||||
proxy_class = Net::HTTP::Proxy( 'proxy.foo.org', 8080 )
|
||||
:
|
||||
proxy_class.start( 'www.ruby-lang.org' ) {|http|
|
||||
# connecting proxy.foo.org:8080
|
||||
:
|
||||
}
|
||||
|
||||
: proxy_class?
|
||||
自身が (Proxy メソッドによって作成された) プロクシ用のクラスならば真。
|
||||
|
||||
: port
|
||||
HTTP のデフォルトポート (80)。
|
||||
|
||||
=== メソッド
|
||||
|
||||
: start
|
||||
: start {|http| .... }
|
||||
TCP コネクションを張り、HTTP セッションを開始します。
|
||||
すでにセッションが開始していたら例外 IOError を発生します。
|
||||
|
||||
イテレータとして呼ばれた時はブロックの間だけセッションを接続し、
|
||||
ブロック終了とともに自動的にセッションを閉じます。
|
||||
|
||||
: active?
|
||||
HTTP セッションが開始されていたら真。
|
||||
|
||||
: address
|
||||
接続するアドレス
|
||||
|
||||
: port
|
||||
接続するポート番号
|
||||
|
||||
: open_timeout
|
||||
: open_timeout=(n)
|
||||
接続時に待つ最大秒数。この秒数たってもコネクションが
|
||||
開かなければ例外 TimeoutError を発生します。
|
||||
|
||||
: read_timeout
|
||||
: read_timeout=(n)
|
||||
読みこみ (read(1) 一回) でブロックしてよい最大秒数。
|
||||
この秒数たっても読みこめなければ例外 TimeoutError を発生します。
|
||||
|
||||
: finish
|
||||
HTTP セッションを終了します。セッション開始前にこのメソッドが
|
||||
呼ばれた場合は例外 IOError を発生します。
|
||||
|
||||
: proxy?
|
||||
プロクシを介して接続するなら真。
|
||||
|
||||
: proxy_address
|
||||
プロクシ経由で接続する HTTP オブジェクトならプロクシのアドレス。
|
||||
そうでないなら nil。
|
||||
|
||||
: proxy_port
|
||||
プロクシ経由で接続する HTTP オブジェクトならプロクシのポート。
|
||||
そうでないなら nil。
|
||||
|
||||
: get( path, header = nil )
|
||||
: get( path, header = nil ) {|str| .... }
|
||||
サーバ上の path にあるエンティティを取得します。また header が nil
|
||||
でなければ、リクエストを送るときにその内容を HTTP ヘッダとして書き
|
||||
こみます。header はハッシュで、「ヘッダ名 => 内容」のような形式で
|
||||
なければいけません。
|
||||
|
||||
返り値は、バージョン 1.1 では HTTPResponse とエンティティボディ文字列の
|
||||
二要素の配列です。1.2 では HTTPResponse ただひとつのみです。この場合、
|
||||
エンティティボディは response.body で得られます。
|
||||
|
||||
ブロックとともに呼ばれた時はエンティティボディを少しづつブロックに
|
||||
与えます。
|
||||
|
||||
1.1 では 3xx (再試行可能なエラー)に対しても例外を発生します。この場合
|
||||
HTTPResponse は例外オブジェクトから err.response で得ることができます。
|
||||
一方 1.2 では全く例外を発生しません。
|
||||
|
||||
# version 1.1 (bundled with Ruby 1.6)
|
||||
response, body = http.get( '/index.html' )
|
||||
|
||||
# version 1.2 (bundled with Ruby 1.7 or later)
|
||||
response = http.get( '/index.html' )
|
||||
|
||||
# compatible in both version
|
||||
response , = http.get( '/index.html' )
|
||||
response.body
|
||||
|
||||
# using block
|
||||
File.open( 'save.txt', 'w' ) {|f|
|
||||
http.get( '/~foo/', nil ) do |str|
|
||||
f.write str
|
||||
end
|
||||
}
|
||||
|
||||
: head( path, header = nil )
|
||||
サーバ上の path にあるエンティティのヘッダのみを取得します。
|
||||
また header が nil でなければリクエストを送るときにその内容を
|
||||
HTTP ヘッダとして書きこみます。header はハッシュで、
|
||||
「ヘッダ名 => 内容」のような形式でなければいけません。
|
||||
|
||||
HTTPResponse オブジェクトを返します。
|
||||
|
||||
1.1 では 3xx (再試行可能なエラー)に対しても例外を発生します。この場合
|
||||
HTTPResponse は例外オブジェクトから err.response で得ることができます。
|
||||
一方 1.2 では全く例外を発生しません。
|
||||
|
||||
response = nil
|
||||
Net::HTTP.start( 'some.www.server', 80 ) {|http|
|
||||
response = http.head( '/index.html' )
|
||||
}
|
||||
p response['content-type']
|
||||
|
||||
: post( path, data, header = nil )
|
||||
: post( path, data, header = nil ) {|str| .... }
|
||||
サーバ上の path にあるエンティティに対し文字列 data を
|
||||
送ります。レスポンスは << メソッドを使って dest に書き
|
||||
こまれます。header は get メソッドと同じです。
|
||||
HTTPResponse オブジェクトと dest の配列を返します。
|
||||
|
||||
イテレータとして呼びだされたときはエンティティボディを少しづつ
|
||||
ブロックに与えます。
|
||||
|
||||
1.1 では 3xx (再試行可能なエラー)に対しても例外を発生します。この場合
|
||||
HTTPResponse は例外オブジェクトから err.response で得ることができます。
|
||||
一方 1.2 では全く例外を発生しません。
|
||||
|
||||
# version 1.1
|
||||
response, body = http.post( '/cgi-bin/search.rb', 'query=subject&target=ruby' )
|
||||
|
||||
# version 1.2
|
||||
response = http.post( '/cgi-bin/search.rb', 'query=subject&target=ruby' )
|
||||
|
||||
# compatible in both version
|
||||
response , = http.post( '/cgi-bin/search.rb', 'query=subject&target=ruby' )
|
||||
|
||||
# using block
|
||||
File.open( 'save.html', 'w' ) {|f|
|
||||
http.post( '/cgi-bin/search.rb',
|
||||
'query=subject&target=ruby' ) do |str|
|
||||
f.write str
|
||||
end
|
||||
}
|
||||
|
||||
: request_get( path, header = nil )
|
||||
: request_get( path, header = nil ) {|response| .... }
|
||||
path にあるエンティティを取得します。HTTPResponse
|
||||
オブジェクトを返します。
|
||||
|
||||
ブロックとともに呼び出されたときは、ブロック実行中は接続を
|
||||
維持したまま HTTPResponse オブジェクトをブロックに渡します。
|
||||
|
||||
このメソッドは HTTP プロトコルに関連した例外は発生させません。
|
||||
|
||||
# example
|
||||
response = http.request_get( '/index.html' )
|
||||
p response['content-type']
|
||||
puts response.body # body is already read
|
||||
|
||||
# using block
|
||||
http.request_get( '/index.html' ) {|response|
|
||||
p response['content-type']
|
||||
response.read_body do |str| # read body now
|
||||
print str
|
||||
end
|
||||
}
|
||||
|
||||
: request_post( path, data, header = nil )
|
||||
: request_post( path, data, header = nil ) {|response| .... }
|
||||
path にあるエンティティを取得します。HTTPResponse
|
||||
オブジェクトを返します。
|
||||
|
||||
ブロックとともに呼び出されたときは、ボディを読みこむ前に
|
||||
HTTPResponse オブジェクトをブロックに渡します。
|
||||
|
||||
このメソッドは HTTP プロトコルに関連した例外は発生させません。
|
||||
|
||||
# example
|
||||
response = http.post2( '/cgi-bin/nice.rb', 'datadatadata...' )
|
||||
p response.status
|
||||
puts response.body # body is already read
|
||||
|
||||
# using block
|
||||
http.post2( '/cgi-bin/nice.rb', 'datadatadata...' ) {|response|
|
||||
p response.status
|
||||
p response['content-type']
|
||||
response.read_body do |str| # read body now
|
||||
print str
|
||||
end
|
||||
}
|
||||
|
||||
: request( request [, data] )
|
||||
: request( request [, data] ) {|response| .... }
|
||||
HTTPResquest オブジェクト request を送信します。POST/PUT の時は data も
|
||||
与えられます (POST/PUT 以外で data を与えると ArgumentError を発生します)。
|
||||
|
||||
ブロックとともに呼びだされたときはボディを読みこまずに HTTPResponse
|
||||
オブジェクトをブロックに与えます。
|
||||
|
||||
このメソッドは HTTP プロトコルに関連した例外は発生させません。
|
||||
|
||||
== class Net::HTTP::Get, Head, Post
|
||||
|
||||
HTTP リクエストを抽象化するクラス。key はすべて大文字小文字を
|
||||
区別しません。
|
||||
|
||||
=== クラスメソッド
|
||||
|
||||
: new
|
||||
HTTP リクエストオブジェクトを生成します。
|
||||
|
||||
=== メソッド
|
||||
|
||||
: self[ key ]
|
||||
key ヘッダフィールドの文字列。
|
||||
key は大文字小文字を区別しません。
|
||||
|
||||
: self[ key ] = val
|
||||
key ヘッダフィールドに val をセットします。
|
||||
key は大文字小文字を区別しません。
|
||||
|
||||
: each {|name, val| .... }
|
||||
ヘッダ名とその値に対するくりかえし。ヘッダ名は小文字で統一されます。
|
||||
|
||||
: basic_auth( account, password )
|
||||
Authrization: ヘッダを basic auth 用にセットします。
|
||||
|
||||
: range
|
||||
Range: ヘッダの示す範囲を Range オブジェクトで返します。
|
||||
|
||||
: range = r
|
||||
: set_range( i, len )
|
||||
範囲を指定してエンティティを取得するためのヘッダ Range: をセットします。
|
||||
r は Range オブジェクト、i, len は始点と長さです。
|
||||
|
||||
: content_length
|
||||
Content-Length: ヘッダの値 (整数)。
|
||||
|
||||
: content_range
|
||||
Content-Range: ヘッダの値 (Range)。
|
||||
|
||||
== class Net::HTTPResponse
|
||||
|
||||
HTTP レスポンスのクラスです。
|
||||
引数がヘッダフィールド名である場合、大文字小文字を区別しません。
|
||||
|
||||
=== メソッド
|
||||
|
||||
: self[ key ]
|
||||
key ヘッダフィールド(文字列)です。たとえばキー 'content-length'
|
||||
に対しては '2048' のような文字列が得られます。
|
||||
key は大文字小文字を区別しません。
|
||||
|
||||
: self[ key ] = val
|
||||
key ヘッダフィールドを value に設定します。
|
||||
key は大文字小文字を区別しません。
|
||||
|
||||
: key?( key )
|
||||
key というヘッダフィールドがあれば真。
|
||||
key は大文字小文字を区別しません。
|
||||
|
||||
: each {|name,value| .... }
|
||||
すべてのヘッダフィールド名とその値のペアに対するくりかえし。
|
||||
|
||||
: canonical_each {|name,value| .... }
|
||||
ヘッダフィールドの正式名とその値のペアに対して繰り返します。
|
||||
|
||||
: code
|
||||
HTTP のリザルトコードです。例えば '302' などです。
|
||||
|
||||
: message
|
||||
HTTP サーバがリザルトコードに付加して返すメッセージです。
|
||||
例えば 'Not Found' などです。
|
||||
|
||||
: read_body( dest = '' )
|
||||
エンティティボディを取得し dest に << メソッドを使って書きこみます。
|
||||
同じ HTTPResponse オブジェクトに対して二回以上呼ばれた場合、
|
||||
二回目からはなにもせずに一回目の返り値をそのまま返します。
|
||||
|
||||
: read_body {|str| .... }
|
||||
エンティティボディを少しづつ取得して順次ブロックに与えます。
|
||||
|
||||
: body
|
||||
エンティティボディです。read_body を呼んでいればその引数 dest、
|
||||
呼んでいなければエンティティボディを文字列として読みこんで返します。
|
||||
|
||||
=end
|
||||
|
|
@ -1,326 +0,0 @@
|
|||
=begin
|
||||
|
||||
= net/pop.rb
|
||||
|
||||
== このライブラリについて
|
||||
|
||||
メールを受信するためのプロトコル 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'
|
||||
|
||||
pop = Net::POP3.new( 'pop3.server.address', 110 )
|
||||
pop.start( 'YourAccount', 'YourPassword' ) ###
|
||||
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
|
||||
puts "#{pop.mails.size} mails popped."
|
||||
end
|
||||
pop.finish ###
|
||||
|
||||
POP サーバはネットワークのむこうに存在するので、なにか仕事をさせる
|
||||
にはその前に開始手続きを、終わったら終了手続きを、行わなければいけ
|
||||
ません。それを行うのが Net::POP3#start と #finish で、POP3 オブジェクト
|
||||
はその二つのメソッドの間でだけ有効になります。
|
||||
|
||||
サーバ上のメールは POPMail オブジェクトとして表現されており、この
|
||||
オブジェクトのメソッドを呼ぶことでメールを取ってきたり消したりする
|
||||
ことができます。POP3#mails はこの POPMail オブジェクトの配列であり、
|
||||
POP3#each_mail はさらに mails.each のショートカットです。
|
||||
|
||||
=== 短くする
|
||||
|
||||
上の例はあえて省略や短縮用メソッドを避けたためにかなり冗長です。
|
||||
まず、ブロック付きの Net::POP3.start を使うことで POP3.new #start
|
||||
#finish を併合できます。
|
||||
|
||||
require 'net/pop'
|
||||
|
||||
Net::POP3.start( 'pop3.server.address', 110 )
|
||||
'YourAccount', 'YourPassword' )
|
||||
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
|
||||
puts "#{pop.mails.size} mails popped."
|
||||
end
|
||||
}
|
||||
|
||||
POP3#delete_all を使うとさらに #each_mail と m.delete を
|
||||
併合できます。
|
||||
|
||||
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
|
||||
|
||||
Net::POP3 クラスのかわりに Net::APOP クラスを使うと、認証時に APOP を
|
||||
使うようになります。また動的にノーマル POP と APOP を選択するには、
|
||||
以下のように Net::POP3.APOP() メソッドを使うのが便利です。
|
||||
|
||||
require 'net/pop'
|
||||
|
||||
# use APOP authentication if $isapop == true
|
||||
pop = Net::POP3.APOP($isapop).new( 'apop.server.address', 110 )
|
||||
pop.start( YourAccount', 'YourPassword' ) {|pop|
|
||||
# Rest code is same.
|
||||
}
|
||||
|
||||
この方法はクラス自体を変えるので、クラスメソッドの start や foreach、
|
||||
delete_all、auth_only なども APOP とともに使えます。
|
||||
|
||||
== Net::POP3 class
|
||||
|
||||
=== クラスメソッド
|
||||
|
||||
: new( address, port = 110, apop = false )
|
||||
Net::POP3 オブジェクトを生成します。まだ接続はしません。
|
||||
apop が真のときは APOP 認証を行うオブジェクトを生成します。
|
||||
|
||||
: start( address, port = 110, account, password )
|
||||
: start( address, port = 110, account, password ) {|pop| .... }
|
||||
address の port 番ポートに接続し、アカウント account パスワード
|
||||
password で POP ログインします。第二引数 port に nil を渡すと
|
||||
POP3 のデフォルトポート(110)を使います。
|
||||
|
||||
Net::POP3.start( addr, port, account, password ) {|pop|
|
||||
pop.each_mail do |m|
|
||||
file.write m.pop
|
||||
m.delete
|
||||
end
|
||||
}
|
||||
|
||||
: APOP( is_apop )
|
||||
bool が真なら Net::APOP クラス、偽なら Net::POP3 クラスを返します。
|
||||
以下の例のように使ってください。
|
||||
|
||||
# example 1
|
||||
pop = Net::POP3::APOP($isapop).new( addr, port )
|
||||
|
||||
# example 2
|
||||
Net::POP3::APOP($isapop).start( addr, port ) {|pop|
|
||||
....
|
||||
}
|
||||
|
||||
: foreach( address, 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, port = 110, account, password )
|
||||
: delete_all( address, port = 110, account, password ) {|mail| .... }
|
||||
POP セッションを開き、サーバ上のメールをすべて削除します。
|
||||
ブロックが与えられた時は削除する前にブロックにそのメールを
|
||||
渡します。以下と同じです。
|
||||
|
||||
# example
|
||||
Net::POP3.delete_all( addr, nil, 'YourAccount', 'YourPassword' ) do |m|
|
||||
m.pop file
|
||||
end
|
||||
|
||||
: auth_only( address, port = 110, account, password )
|
||||
POP セッションを開き認証だけを行って接続を切ります。
|
||||
POP before SMTP 専用です。
|
||||
|
||||
# example
|
||||
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' ) {|pop|
|
||||
allmails = pop.mails.collect {|popmail| popmail.pop }
|
||||
}
|
||||
|
||||
: 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
|
||||
|
|
@ -1,194 +0,0 @@
|
|||
=begin
|
||||
|
||||
= net/smtp.rb
|
||||
|
||||
== このライブラリについて
|
||||
|
||||
メールを送信するためのプロトコル SMTP (Simple Mail Transfer Protocol)
|
||||
を扱うライブラリです。ヘッダなどメールのデータを扱うことはできません。
|
||||
SMTP の実装は [RFC2821] ((<URL:http://www.ietf.org/rfc/rfc2821.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
|
||||
Загрузка…
Ссылка в новой задаче