1berry/ruby
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

* protocol.rb,smtp.rb,pop.rb,http.rb: modify document.

Browse Source 
git-svn-id: svn+ssh://ci.ruby-lang.org/ruby/trunk@1548 b2dd03c8-39d4-4d8f-98ff-823fe69b080e
This commit is contained in:
aamine 2001-06-27 00:59:08 +00:00
parent 37b3f674a7
commit cf37626401
3 changed files with 189 additions and 173 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

77
lib/net/http.rb
View File

@ -27,7 +27,7 @@ For details of HTTP, refer [RFC2616]
=== Getting Document From Server === Getting Document From Server
Be care to ',' (comma) putted after "response". Be care to ',' (comma) putted after "response".
This is required for feature compatibility. This is required for compatibility.
require 'net/http' require 'net/http'
Net::HTTP.start( 'some.www.server', 80 ) {|http| Net::HTTP.start( 'some.www.server', 80 ) {|http|
@ -73,14 +73,17 @@ there's no need to change code if there's proxy or not.
Net::HTTP.version_1_1 Net::HTTP.version_1_1
host = 'www.ruby-lang.org' host = 'www.ruby-lang.org'
path = '/'
begin begin
Net::HTTP.start( host, 80 ) {|http| Net::HTTP.start( host, 80 ) {|http|
response , = http.get('/') response , = http.get(path)
print response.body
} }
rescue Net::ProtoRetriableError => err rescue Net::ProtoRetriableError => err
if m = %r<http:([^/]+)>.match( err.response['location'] ) then if m = %r<http://([^/]+)>.match( err.response['location'] ) then
host = m[1].strip host = m[1].strip
retry path = m.post_match
retry
end end
end end
@ -131,8 +134,7 @@ Yes, this is not thread-safe.
: new( address = 'localhost', port = 80, proxy_addr = nil, proxy_port = nil ) : new( address = 'localhost', port = 80, proxy_addr = nil, proxy_port = nil )
creates a new Net::HTTP object. creates a new Net::HTTP object.
If proxy_addr is given, this method is equals to If proxy_addr is given, creates an Net::HTTP object with proxy support.
Net::HTTP::Proxy(proxy_addr,proxy_port).
: start( address = 'localhost', port = 80, proxy_addr = nil, proxy_port = nil ) : start( address = 'localhost', port = 80, proxy_addr = nil, proxy_port = nil )
: start( address = 'localhost', port = 80, proxy_addr = nil, proxy_port = nil ) {|http| .... } : start( address = 'localhost', port = 80, proxy_addr = nil, proxy_port = nil ) {|http| .... }
@ -145,15 +147,14 @@ Yes, this is not thread-safe.
return value is a String. return value is a String.
: get_print( address, path, port = 80 ) : get_print( address, path, port = 80 )
gets entity body from path and print it. gets entity body from path and output it to $stdout.
return value is an entity body (a String).
: Proxy( address, port = 80 ) : Proxy( address, port = 80 )
creates a HTTP proxy class. creates a HTTP proxy class.
Arguments are address/port of proxy host. Arguments are address/port of proxy host.
You can replace HTTP class by this proxy class. You can replace HTTP class with created proxy class.
If ADDRESS is nil, this method returns self (Net::HTTP class). If ADDRESS is nil, this method returns self (Net::HTTP).
# example # example
proxy_class = Net::HTTP::Proxy( 'proxy.foo.org', 8080 ) proxy_class = Net::HTTP::Proxy( 'proxy.foo.org', 8080 )
@ -168,7 +169,7 @@ Yes, this is not thread-safe.
If self is a class which was created by HTTP::Proxy(), true. If self is a class which was created by HTTP::Proxy(), true.
: port : port
HTTP default port (80). default HTTP port (80).
=== Instance Methods === Instance Methods
@ -208,30 +209,32 @@ Yes, this is not thread-safe.
true if self is a HTTP proxy class true if self is a HTTP proxy class
: proxy_address : proxy_address
address of proxy host. If self is not a proxy, nil. address of proxy host. If self does not use a proxy, nil.
: proxy_port : proxy_port
port number of proxy host. If self is not a proxy, nil. port number of proxy host. If self does not use a proxy, nil.
: get( path, header = nil, dest = '' ) : get( path, header = nil, dest = '' )
: get( path, header = nil ) {|str| .... } : get( path, header = nil ) {|str| .... }
gets data from "path" on connecting host. gets data from PATH on the connecting host.
"header" must be a Hash like { 'Accept' => '*/*', ... }. HEADER must be a Hash like { 'Accept' => '*/*', ... }.
Response body is written into "dest" by using "<<" method. Response body is written into DEST by using "<<" method.
This method returns Net::HTTPResponse object. This method returns Net::HTTPResponse object.
If called with block, give a part String of entity body. If called with block, gives entity body little by little
to the block (as String).
In version 1.1, this method might raises exception for also In version 1.1, this method might raises exception for also
3xx (redirect). On the case you can get response object by 3xx (redirect). On the case you can get a HTTPResponse object
err.response. by "anException.response".
In version 1.2, this method never raises exception. In version 1.2, this method never raises exception.
# version 1.1 (Ruby 1.6) # version 1.1 (bundled with Ruby 1.6)
response, body = http.get( '/index.html' ) response, body = http.get( '/index.html' )
# version 1.2 (Ruby 1.7 or later) # version 1.2 (bundled with Ruby 1.7 or later)
response = http.get( '/index.html' ) response = http.get( '/index.html' )
# compatible in both version # compatible in both version
@ -244,16 +247,20 @@ Yes, this is not thread-safe.
f.write str f.write str
end end
} }
# some effect # same effect
File.open( 'save.txt', 'w' ) {|f| File.open( 'save.txt', 'w' ) {|f|
http.get '/~foo/', nil, f http.get '/~foo/', nil, f
} }
: head( path, header = nil ) : head( path, header = nil )
gets only header from "path" on connecting host. gets only header from PATH on the connecting host.
"header" is a Hash like { 'Accept' => '*/*', ... }. HEADER is a Hash like { 'Accept' => '*/*', ... }.
This method returns a Net::HTTPResponse object. This method returns a Net::HTTPResponse object.
You can http header from this object like:
In version 1.1, this method might raises exception for also
3xx (redirect). On the case you can get a HTTPResponse object
by "anException.response".
response = nil response = nil
Net::HTTP.start( 'some.www.server', 80 ) {|http| Net::HTTP.start( 'some.www.server', 80 ) {|http|
@ -274,6 +281,10 @@ Yes, this is not thread-safe.
If called with block, gives a part of entity body string. If called with block, gives a part of entity body string.
In version 1.1, this method might raises exception for also
3xx (redirect). On the case you can get a HTTPResponse object
by "anException.response".
# version 1.1 # version 1.1
response, body = http.post( '/index.html', 'querytype=subject&target=ruby' ) response, body = http.post( '/index.html', 'querytype=subject&target=ruby' )
# version 1.2 # version 1.2
@ -292,13 +303,15 @@ Yes, this is not thread-safe.
http.post '/index.html', 'querytype=subject&target=ruby', nil, f http.post '/index.html', 'querytype=subject&target=ruby', nil, f
} }
: request( request, [data] ) : request( request [, data] )
: request( request, [src] ) {|response| .... } : request( request [, data] ) {|response| .... }
sends REQUEST to (remote) http server. This method also writes sends a HTTPRequest object REQUEST to (remote) http server.
string from DATA string if REQUEST is a post/put request. This method also writes string from DATA string if REQUEST is
(giving DATA for get/head request causes ArgumentError.) a post/put request. Giving DATA for get/head request causes
ArgumentError.
If called with block, gives a HTTPResponse object to the block. If called with block, gives a HTTPResponse object to the block
with connecting server.
== class Net::HTTP::Get, Head, Post == class Net::HTTP::Get, Head, Post

159
lib/net/pop.rb
View File

@ -28,64 +28,67 @@ This example retrieves mails from server and delete it (on server).
Mails are written in file named 'inbox/1', 'inbox/2', .... Mails are written in file named 'inbox/1', 'inbox/2', ....
Replace 'pop3.server.address' your POP3 server address. Replace 'pop3.server.address' your POP3 server address.
require 'net/pop'
require 'net/pop' Net::POP3.start( 'pop3.server.address', 110,
'YourAccount', 'YourPassword' ) {|pop|
Net::POP3.start( 'pop3.server.address', 110, if pop.mails.empty? then
'YourAccount', 'YourPassword' ) {|pop| puts 'no mail.'
if pop.mails.empty? then else
puts 'no mail.' i = 0
else pop.each_mail do |m| # or "pop.mails.each ..."
i = 0 File.open( 'inbox/' + i.to_s, 'w' ) {|f|
pop.each_mail do |m| # or "pop.mails.each ..." f.write m.pop
File.open( 'inbox/' + i.to_s, 'w' ) do |f| }
f.write m.pop m.delete
i += 1
end end
m.delete
i += 1
end end
end puts "#{pop.mails.size} mails popped."
puts "#{pop.mails.size} mails popped." }
}
=== Shorter Version === Shorter Version
require 'net/pop' require 'net/pop'
i = 0 Net::POP3.start( 'pop3.server.address', 110,
Net::POP3.start( 'pop3.server.address', 110, 'YourAccount', 'YourPassword' ) {|pop|
'YourAccount', 'YourPassword' ) {|pop| if pop.mails.empty? then
pop.delete_all do |m| 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
}
And here is more shorter example.
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| File.open( 'inbox/' + i.to_s, 'w' ) {|f|
f.write m.pop f.write m.pop
} }
i += 1 i += 1
end end
}
And this is more shorter example.
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
=== Writing to File directly === Writing to File directly
All examples above get mail as one big string. All examples above get mail as one big string.
This example does not create such one. This example does not create such one.
require 'net/pop' require 'net/pop'
Net::POP3.delete_all( 'pop3.server.address', 110, Net::POP3.delete_all( 'pop3.server.address', 110,
'YourAccount', 'YourPassword' ) do |m| 'YourAccount', 'YourPassword' ) do |m|
File.open( 'inbox', 'w' ) {|f| File.open( 'inbox', 'w' ) {|f|
m.pop f #### m.pop f ####
} }
end end
=== Using APOP === Using APOP
@ -93,57 +96,57 @@ net/pop also supports APOP authentication. There's two way to use APOP:
(1) using APOP class instead of POP3 (1) using APOP class instead of POP3
(2) passing true for fifth argument of POP3.start (2) passing true for fifth argument of POP3.start
# (1) # (1)
require 'net/pop' require 'net/pop'
Net::APOP.start( 'apop.server.address', 110, Net::APOP.start( 'apop.server.address', 110,
'YourAccount', 'YourPassword' ) {|pop| 'YourAccount', 'YourPassword' ) {|pop|
# Rest code is same. # Rest code is same.
} }
# (2) # (2)
require 'net/pop' require 'net/pop'
Net::POP3.start( 'apop.server.address', 110, Net::POP3.start( 'apop.server.address', 110,
'YourAccount', 'YourPassword', 'YourAccount', 'YourPassword',
true #### true ####
) {|pop| ) {|pop|
# Rest code is same. # Rest code is same.
} }
== Net::POP3 class == Net::POP3 class
=== Class Methods === Class Methods
: new( address = 'localhost', port = 110, apop = false ) : new( address = 'localhost', port = 110, apop = false )
creates a new Net::POP3 object. creates a new Net::POP3 object.
This method does not open TCP connection yet. This method does not open TCP connection yet.
: start( address = 'localhost', port = 110, account, password ) : start( address = 'localhost', port = 110, account, password )
: start( address = 'localhost', port = 110, account, password ) {|pop| .... } : start( address = 'localhost', port = 110, account, password ) {|pop| .... }
equals to Net::POP3.new( address, port ).start( account, password ) equals to Net::POP3.new( address, port ).start( account, password )
Net::POP3.start( addr, port, account, password ) do |pop| Net::POP3.start( addr, port, account, password ) do |pop|
pop.each_mail do |m| pop.each_mail do |m|
file.write m.pop file.write m.pop
m.delete m.delete
end end
end end
: foreach( address = 'localhost', port = 110, account, password ) {|mail| .... } : foreach( address = 'localhost', port = 110, account, password ) {|mail| .... }
starts protocol and iterate for each POPMail object. starts POP3 protocol and iterates for each POPMail object.
This method equals to This method equals to
Net::POP3.start( address, port, account, password ) do |pop| Net::POP3.start( address, port, account, password ) {|pop|
pop.each do |m| pop.each_mail do |m|
yield m yield m
end end
end }
Typical usage: # example
Net::POP3.foreach( 'your.pop.server', 110,
Net::POP3.foreach( addr, nil, acnt, pass ) do |m| 'YourAccount', 'YourPassword' ) do |m|
m.pop file file.write m.pop
m.delete m.delete if $DELETE
end end
: delete_all( address = 'localhost', port = 110, account, password ) : delete_all( address = 'localhost', port = 110, account, password )
: delete_all( address = 'localhost', port = 110, account, password ) {|mail| .... } : delete_all( address = 'localhost', port = 110, account, password ) {|mail| .... }
@ -229,7 +232,7 @@ net/pop also supports APOP authentication. There's two way to use APOP:
pop.auth_only 'YourAccount', 'YourPassword' pop.auth_only 'YourAccount', 'YourPassword'
: reset : reset
reset the session. All "deleted mark" are removed. reset the session. All "deleted mark" are removed.
== Net::APOP == Net::APOP

126
lib/net/smtp.rb
View File

@ -36,10 +36,10 @@ is port number. Using SMTP.start with block is the most simple way
to do it. SMTP Connection is closed automatically after block is to do it. SMTP Connection is closed automatically after block is
executed. executed.
require 'net/smtp' require 'net/smtp'
Net::SMTP.start( 'your.smtp.server', 25 ) {|smtp| Net::SMTP.start( 'your.smtp.server', 25 ) {|smtp|
# use smtp object only in this block # use smtp object only in this block
} }
Replace 'your.smtp.server' by your SMTP server. Normally Replace 'your.smtp.server' by your SMTP server. Normally
your system manager or internet provider is supplying a server your system manager or internet provider is supplying a server
@ -47,19 +47,19 @@ for you.
Then you can send mail. Then you can send mail.
require 'net/smtp' require 'net/smtp'
Net::SMTP.start( 'your.smtp.server', 25 ) {|smtp| Net::SMTP.start( 'your.smtp.server', 25 ) {|smtp|
smtp.send_mail <<EndOfMail, 'your@mail.address', 'to@some.domain' smtp.send_mail <<EndOfMail, 'your@mail.address', 'to@some.domain'
From: Your Name <your@mail.address> From: Your Name <your@mail.address>
To: Dest Address <to@some.domain> To: Dest Address <to@some.domain>
Subject: test mail Subject: test mail
Date: Sat, 23 Jun 2001 16:26:43 +0900 Date: Sat, 23 Jun 2001 16:26:43 +0900
Message-Id: <unique.message.id.string@some.domain> Message-Id: <unique.message.id.string@some.domain>
This is test mail. This is test mail.
EndOfMail EndOfMail
} }
=== Sending Mails from Any Sources === Sending Mails from Any Sources
@ -67,20 +67,20 @@ In an example above I sent mail from String (here document literal).
SMTP#send_mail accepts any objects which has "each" method SMTP#send_mail accepts any objects which has "each" method
like File and Array. like File and Array.
require 'net/smtp' require 'net/smtp'
Net::SMTP.start( 'your.smtp.server', 25 ) {|smtp| Net::SMTP.start( 'your.smtp.server', 25 ) {|smtp|
File.open( 'Mail/draft/1' ) {|f| File.open( 'Mail/draft/1' ) {|f|
smtp.send_mail f, 'your@mail.address', 'to@some.domain' smtp.send_mail f, 'your@mail.address', 'to@some.domain'
}
} }
}
=== Giving "Hello" Domain === Giving "Hello" Domain
If your machine does not have canonical host name, maybe you If your machine does not have canonical host name, maybe you
must designate the third argument of SMTP.start. must designate the third argument of SMTP.start.
Net::SMTP.start( 'your.smtp.server', 25, Net::SMTP.start( 'your.smtp.server', 25,
'mail.from.domain' ) {|smtp| 'mail.from.domain' ) {|smtp|
This argument gives MAILFROM domain, the domain name that This argument gives MAILFROM domain, the domain name that
you send mail from. SMTP server might judge if he (or she?) you send mail from. SMTP server might judge if he (or she?)
@ -91,32 +91,32 @@ send or reject SMTP session by this data.
=== Class Methods === Class Methods
: new( address = 'localhost', port = 25 ) : new( address = 'localhost', port = 25 )
creates a new Net::SMTP object. creates a new Net::SMTP object.
: start( address = 'localhost', port = 25, helo_domain = Socket.gethostname, account = nil, password = nil, authtype = nil ) : start( address = 'localhost', port = 25, helo_domain = Socket.gethostname, account = nil, password = nil, authtype = nil )
: start( address = 'localhost', port = 25, helo_domain = Socket.gethostname, account = nil, password = nil, authtype = nil ) {|smtp| .... } : start( address = 'localhost', port = 25, helo_domain = Socket.gethostname, account = nil, password = nil, authtype = nil ) {|smtp| .... }
is equal to is equal to
Net::SMTP.new(address,port).start(helo_domain,account,password,authtype) Net::SMTP.new(address,port).start(helo_domain,account,password,authtype)
# example # example
Net::SMTP.start( 'your.smtp.server' ) { Net::SMTP.start( 'your.smtp.server' ) {
smtp.send_mail mail_string, 'from@mail.address', 'dest@mail.address' smtp.send_mail mail_string, 'from@mail.address', 'dest@mail.address'
} }
=== Instance Methods === Instance Methods
: start( helo_domain = <local host name>, account = nil, password = nil, authtype = nil ) : 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| .... } : start( helo_domain = <local host name>, account = nil, password = nil, authtype = nil ) {|smtp| .... }
opens TCP connection and starts SMTP session. opens TCP connection and starts SMTP session.
If protocol had been started, do nothing and return false. If protocol had been started, do nothing and return false.
HELO_DOMAIN is a domain that you'll dispatch mails from. HELO_DOMAIN is a domain that you'll dispatch mails from.
When this methods is called with block, give a SMTP object to block and When this methods is called with block, give a SMTP object to block and
close session after block call finished. close session after block call finished.
If both of account and password are given, is trying to get If both of account and password are given, is trying to get
authentication by using AUTH command. :plain or :cram_md5 is authentication by using AUTH command. :plain or :cram_md5 is
allowed for AUTHTYPE. allowed for AUTHTYPE.
: active? : active?
true if SMTP session is started. true if SMTP session is started.
@ -144,38 +144,38 @@ send or reject SMTP session by this data.
If SMTP session had not started, do nothing and return false. If SMTP session had not started, do nothing and return false.
: send_mail( mailsrc, from_addr, *to_addrs ) : send_mail( mailsrc, from_addr, *to_addrs )
This method sends MAILSRC as mail. A SMTP object read strings This method sends MAILSRC as mail. A SMTP object read strings
from MAILSRC by calling "each" iterator, with converting them from MAILSRC by calling "each" iterator, with converting them
into CRLF ("\r\n") terminated string when write. into CRLF ("\r\n") terminated string when write.
FROM_ADDR must be a String, representing source mail address. FROM_ADDR must be a String, representing source mail address.
TO_ADDRS must be Strings or an Array of Strings, representing TO_ADDRS must be Strings or an Array of Strings, representing
destination mail addresses. destination mail addresses.
# example # example
Net::SMTP.start( 'your.smtp.server' ) {|smtp| Net::SMTP.start( 'your.smtp.server' ) {|smtp|
smtp.send_mail mail_string, smtp.send_mail mail_string,
'from@mail.address', 'from@mail.address',
'dest@mail.address' 'dest2@mail.address' 'dest@mail.address' 'dest2@mail.address'
} }
: ready( from_addr, *to_addrs ) {|adapter| .... } : ready( from_addr, *to_addrs ) {|adapter| .... }
This method stands by the SMTP object for sending mail and This method stands by the SMTP object for sending mail and
give adapter object to the block. ADAPTER accepts only "write" give adapter object to the block. ADAPTER accepts only "write"
method. method.
FROM_ADDR must be a String, representing source mail address. FROM_ADDR must be a String, representing source mail address.
TO_ADDRS must be Strings or an Array of Strings, representing TO_ADDRS must be Strings or an Array of Strings, representing
destination mail addresses. destination mail addresses.
# example # example
Net::SMTP.start( 'your.smtp.server', 25 ) {|smtp| Net::SMTP.start( 'your.smtp.server', 25 ) {|smtp|
smtp.ready( 'from@mail.addr', 'dest@mail.addr' ) do |adapter| smtp.ready( 'from@mail.addr', 'dest@mail.addr' ) do |adapter|
adapter.write str1 adapter.write str1
adapter.write str2 adapter.write str2
adapter.write str3 adapter.write str3
end end
} }
== Exceptions == Exceptions