зеркало из https://github.com/github/ruby.git
Really cvs rm these files from HEAD.
git-svn-id: svn+ssh://ci.ruby-lang.org/ruby/trunk@3268 b2dd03c8-39d4-4d8f-98ff-823fe69b080e
This commit is contained in:
knu
Родитель
c56fa0649d
Коммит
2a54402839
|
|
@ -1,502 +0,0 @@
|
||||||
=begin
|
|
||||||
|
|
||||||
= net/http.rb
|
|
||||||
|
|
||||||
== このライブラリについて
|
|
||||||
|
|
||||||
汎用データ転送プロトコル HTTP version 1.1 を扱うライブラリです。
|
|
||||||
実装は [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'
|
|
||||||
# or
|
|
||||||
Net::HTTP.get_print URI.parse('http://www.example.com/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'
|
|
||||||
|
|
||||||
def read_uri( uri_str )
|
|
||||||
response = Net::HTTP.get_response(URI.parse(uri_str))
|
|
||||||
case response
|
|
||||||
when Net::HTTPSuccess then response
|
|
||||||
when Net::HTTPRedirection then read_uri(response['location'])
|
|
||||||
else
|
|
||||||
response.error!
|
|
||||||
end
|
|
||||||
end
|
|
||||||
|
|
||||||
print read_uri('http://www.ruby-lang.org')
|
|
||||||
|
|
||||||
HTTPSuccess や HTTPRedirection は HTTPResponse クラスの下位クラスです。
|
|
||||||
HTTPResponse オブジェクトはそれぞれ HTTP レスポンスのステータスによって
|
|
||||||
異るクラスに属しており、そのクラスで結果を分類できます。どのようなクラスが
|
|
||||||
用意されているのかについては「HTTP レスポンスクラス群」の節を見てください。
|
|
||||||
|
|
||||||
=== Basic 認証
|
|
||||||
|
|
||||||
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
|
|
||||||
}
|
|
||||||
|
|
||||||
=== HTTP レスポンスクラス群
|
|
||||||
|
|
||||||
以下に HTTP 1.1 のリザルトコードとそれに対応するレスポンスクラスを
|
|
||||||
示します。クラスはすべて Net モジュールの中で定義されており、
|
|
||||||
インデントが継承関係を表わしています。
|
|
||||||
|
|
||||||
xxx HTTPResponse
|
|
||||||
|
|
||||||
1xx HTTPInformation
|
|
||||||
100 HTTPContinue
|
|
||||||
101 HTTPSwitchProtocol
|
|
||||||
|
|
||||||
2xx HTTPSuccess
|
|
||||||
200 HTTPOK
|
|
||||||
201 HTTPCreated
|
|
||||||
202 HTTPAccepted
|
|
||||||
203 HTTPNonAuthoritativeInformation
|
|
||||||
204 HTTPNoContent
|
|
||||||
205 HTTPResetContent
|
|
||||||
206 HTTPPartialContent
|
|
||||||
|
|
||||||
3xx HTTPRedirection
|
|
||||||
300 HTTPMultipleChoice
|
|
||||||
301 HTTPMovedPermanently
|
|
||||||
302 HTTPFound
|
|
||||||
303 HTTPSeeOther
|
|
||||||
304 HTTPNotModified
|
|
||||||
305 HTTPUseProxy
|
|
||||||
307 HTTPTemporaryRedirect
|
|
||||||
|
|
||||||
4xx HTTPClientError
|
|
||||||
400 HTTPBadRequest
|
|
||||||
401 HTTPUnauthorized
|
|
||||||
402 HTTPPaymentRequired
|
|
||||||
403 HTTPForbidden
|
|
||||||
404 HTTPNotFound
|
|
||||||
405 HTTPMethodNotAllowed
|
|
||||||
406 HTTPNotAcceptable
|
|
||||||
407 HTTPProxyAuthenticationRequired
|
|
||||||
408 HTTPRequestTimeOut
|
|
||||||
409 HTTPConflict
|
|
||||||
410 HTTPGone
|
|
||||||
411 HTTPLengthRequired
|
|
||||||
412 HTTPPreconditionFailed
|
|
||||||
413 HTTPRequestEntityTooLarge
|
|
||||||
414 HTTPRequestURITooLong
|
|
||||||
415 HTTPUnsupportedMediaType
|
|
||||||
416 HTTPRequestedRangeNotSatisfiable
|
|
||||||
417 HTTPExpectationFailed
|
|
||||||
|
|
||||||
5xx HTTPServerError
|
|
||||||
500 HTTPInternalServerError
|
|
||||||
501 HTTPNotImplemented
|
|
||||||
502 HTTPBadGateway
|
|
||||||
503 HTTPServiceUnavailable
|
|
||||||
504 HTTPGatewayTimeOut
|
|
||||||
505 HTTPVersionNotSupported
|
|
||||||
|
|
||||||
xxx HTTPUnknownResponse
|
|
||||||
|
|
||||||
== 新しい仕様への変更と移行措置について
|
|
||||||
|
|
||||||
Ruby 1.6 には http.rb 1.1、Ruby 1.7 には http.rb 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 )
|
|
||||||
新しい Net::HTTP オブジェクトを生成し HTTP セッションを
|
|
||||||
開始したうえで返します。
|
|
||||||
|
|
||||||
: start( address, port = 80, proxy_addr = nil, proxy_port = nil ) {|http| .... }
|
|
||||||
新しい Net::HTTP オブジェクトを生成しブロックに渡します。
|
|
||||||
ブロック実行中のみ HTTP セッションを維持します。
|
|
||||||
|
|
||||||
ブロックの返り値をそのまま返します。
|
|
||||||
|
|
||||||
: get_print( uri )
|
|
||||||
: get_print( address, path, port = 80 )
|
|
||||||
uri または address path port で指定されたエンティティを
|
|
||||||
取得し stdout に出力します。
|
|
||||||
|
|
||||||
Net::HTTP.get_print URI.parse('http://www.example.com')
|
|
||||||
|
|
||||||
: get( uri )
|
|
||||||
: get( address, path, port = 80 )
|
|
||||||
uri または address path port で指定されたエンティティを
|
|
||||||
取得し文字列で返します。
|
|
||||||
|
|
||||||
print Net::HTTP.get(URI.parse('http://www.example.com'))
|
|
||||||
|
|
||||||
: get_response( uri )
|
|
||||||
: get_response( address, path, port = 80 )
|
|
||||||
uri または address path port で指定されたエンティティを
|
|
||||||
取得し Net::HTTPResponse オブジェクトで返します。
|
|
||||||
|
|
||||||
res = Net::HTTP.get_response(URI.parse('http://www.example.com'))
|
|
||||||
print res.body
|
|
||||||
|
|
||||||
: 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 を発生します。
|
|
||||||
|
|
||||||
イテレータとして呼ばれた時はブロックの間だけセッションを
|
|
||||||
維持し、ブロック終了とともに自動的にセッションを終了します。
|
|
||||||
|
|
||||||
: started?
|
|
||||||
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::HTTPRequest
|
|
||||||
|
|
||||||
HTTP リクエストを抽象化するクラス。実際には下位クラスの
|
|
||||||
Net::HTTP::Get, Post, Head を使います。
|
|
||||||
|
|
||||||
=== クラスメソッド
|
|
||||||
|
|
||||||
: 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,205 +0,0 @@
|
||||||
=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
|
|
||||||
Загрузка…
Ссылка в новой задаче