diff options
author | aamine <aamine@b2dd03c8-39d4-4d8f-98ff-823fe69b080e> | 2001-06-26 23:49:21 +0000 |
---|---|---|
committer | aamine <aamine@b2dd03c8-39d4-4d8f-98ff-823fe69b080e> | 2001-06-26 23:49:21 +0000 |
commit | c664027a342785089cc09169ff167350e840baa9 (patch) | |
tree | 2b74c20ddbfd9371414294e4c34ea3ce1e5afe95 /lib/net/pop.rb | |
parent | 10e80b2402f7c0fd79df86767a11ba4e4b1bfa95 (diff) |
aamine
* lib/net/pop.rb: new methods POP3.auth_only, POP3#auth_only
* lib/net/http.rb: HTTP.Proxy returns self if ADDRESS is nil.
* lib/net/protocol.rb: new method ProtocolError#response
* lib/net/protocol.rb,smtp.rb,pop.rb,http.rb: add document.
git-svn-id: svn+ssh://ci.ruby-lang.org/ruby/trunk@1546 b2dd03c8-39d4-4d8f-98ff-823fe69b080e
Diffstat (limited to 'lib/net/pop.rb')
-rw-r--r-- | lib/net/pop.rb | 337 |
1 files changed, 230 insertions, 107 deletions
diff --git a/lib/net/pop.rb b/lib/net/pop.rb index c61e09735d..fee68f25a0 100644 --- a/lib/net/pop.rb +++ b/lib/net/pop.rb @@ -1,25 +1,115 @@ =begin -= net/pop.rb version 1.2.0 += net/pop.rb version 1.2.1 - Copyright (C) 1999-2001 Yukihiro Matsumoto +Copyright (c) 1999-2001 Yukihiro Matsumoto - written & maintained by Minero Aoki <aamine@dp.u-netsurf.ne.jp> +written & maintained by Minero Aoki <aamine@loveruby.net> - This program is free software. You can re-distribute and/or - modify this program under the same terms as Ruby itself, - GNU General Public License or Ruby License. +This program is free software. You can re-distribute and/or +modify this program under the same terms as Ruby itself, +Ruby Distribute License or GNU General Public License. - Japanese version of this document is in "net" full package. - You can get it from RAA (Ruby Application Archive). RAA is: - http://www.ruby-lang.org/en/raa.html +NOTE: You can get Japanese version of this document from +Ruby Documentation Project (RDP): +((<URL:http://www.ruby-lang.org/~rubikitch/RDP.cgi>)) +== What is This Module? -== Net::POP3 +This module provides your program the functions to retrieve +mails via POP3, Post Office Protocol version 3. For details +of POP3, refer [RFC1939] ((<URL:http://www.ietf.org/rfc/rfc1939.txt>)). -=== Super Class +== Examples + +=== Retrieving Mails + +This example retrieves mails from server and delete it (on server). +Mails are written in file named 'inbox/1', 'inbox/2', .... +Replace 'pop3.server.address' your 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' ) do |f| + f.write m.pop + end + m.delete + i += 1 + end + end + puts "#{pop.mails.size} mails popped." + } + +=== Shorter Version + + require 'net/pop' + i = 0 + Net::POP3.start( 'pop3.server.address', 110, + 'YourAccount', 'YourPassword' ) {|pop| + pop.delete_all do |m| + File.open( 'inbox/' + i.to_s, 'w' ) {|f| + f.write m.pop + } + i += 1 + 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 -Net::Protocol +=== Writing to File directly + +All examples above get mail as one big string. +This example does not create such one. + + require 'net/pop' + Net::POP3.delete_all( 'pop3.server.address', 110, + 'YourAccount', 'YourPassword' ) do |m| + File.open( 'inbox', 'w' ) {|f| + m.pop f #### + } + end + +=== Using APOP + +net/pop also supports APOP authentication. There's two way to use APOP: +(1) using APOP class instead of POP3 +(2) passing true for fifth argument of POP3.start + + # (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 === Class Methods @@ -31,10 +121,9 @@ Net::Protocol : start( address = 'localhost', port = 110, account, password ) {|pop| .... } equals to Net::POP3.new( address, port ).start( account, password ) - # typical usage - Net::POP3.start( addr, port, acnt, pass ) do |pop| + Net::POP3.start( addr, port, account, password ) do |pop| pop.each_mail do |m| - any_file.write m.pop + file.write m.pop m.delete end end @@ -49,9 +138,8 @@ Net::Protocol end end - . + Typical usage: - # typical usage Net::POP3.foreach( addr, nil, acnt, pass ) do |m| m.pop file m.delete @@ -59,120 +147,140 @@ Net::Protocol : delete_all( address = 'localhost', port = 110, account, password ) : delete_all( address = 'localhost', port = 110, account, password ) {|mail| .... } - starts POP3 session and delete all mails. - If block is given, iterates for each POPMail object before delete. + starts POP3 session and delete all mails. + If block is given, iterates for each POPMail object before delete. + + # example + Net::POP3.delete_all( addr, nil, 'YourAccount', 'YourPassword' ) do |m| + m.pop file + end + +: auth_only( address = 'localhost', port = 110, account, password ) + (just for POP-before-SMTP) + opens POP3 session and does autholize and quit. + This method must not be called while POP3 session is opened. + + # example + pop = Net::POP3.auth_only( 'your.pop3.server', + nil, # using default (110) + 'YourAccount', + 'YourPassword' ) - # typical usage - Net::POP3.delete_all( addr, nil, acnt, pass ) do |m| - m.pop file - end - === Instance Methods : start( account, password ) : start( account, password ) {|pop| .... } - starts POP3 session. + starts POP3 session. + + When called with block, gives a POP3 object to block and + closes the session after block call finish. + +: active? + true if POP3 session is started. + +: address + the address to connect + +: port + the port number to connect - When called with block, gives a POP3 object to block and - closes the session after block call finish. +: open_timeout +: open_timeout=(n) + seconds to wait until connection is opened. + If POP3 object cannot open a conection in this seconds, + it raises TimeoutError exception. + +: read_timeout +: read_timeout=(n) + seconds to wait until reading one block (by one read(1) call). + If POP3 object cannot open a conection in this seconds, + it raises TimeoutError exception. + +: finish + finishes POP3 session. + If POP3 session had not be started, does nothing and return false. : mails - an array of ((URL:#POPMail)). - This array is renewed when session started. + an array of Net::POPMail objects. + This array is renewed when session started. : each_mail {|popmail| .... } : each {|popmail| .... } - is equals to "pop3.mails.each" + is equals to "pop3.mails.each" : delete_all : delete_all {|popmail| .... } - deletes all mails. - If called with block, gives mails to the block before deleting. - - # example 1 - # pop and delete all mails - n = 1 - pop.delete_all do |m| - File.open("inbox/#{n}") {|f| f.write m.pop } - n += 1 - end + deletes all mails on server. + If called with block, gives mails to the block before deleting. + + # example + n = 1 + pop.delete_all do |m| + File.open("inbox/#{n}") {|f| f.write m.pop } + n += 1 + end - # example 2 - # clear all mails on server - Net::POP3.start( addr, port, acc, pass ) do |pop| - pop.delete_all - end +: auth_only( account, password ) + (just for POP-before-SMTP) + opens POP3 session and does autholize and quit. + This method must not be called while POP3 session is opened. + # example + pop = Net::POP3.new( 'your.pop3.server' ) + pop.auth_only 'YourAccount', 'YourPassword' : reset reset the session. All "deleted mark" are removed. - == Net::APOP This class defines no new methods. Only difference from POP3 is using APOP authentification. === Super Class - Net::POP3 - == Net::POPMail A class of mail which exists on POP server. -=== Super Class - -Object - - -=== Methods +=== Instance Methods : pop( dest = '' ) - This method fetches a mail and write to 'dest' using '<<' method. - - # usage example + This method fetches a mail and write to 'dest' using '<<' method. - mailarr = [] - POP3.start( 'localhost', 110 ) do |pop| - pop.each_mail do |popm| - mailarr.push popm.pop # all() returns 'dest' (this time, string) - # or, you can also - # popm.pop( $stdout ) # write mail to stdout - - # maybe you also want to delete mail after popping - popm.delete - end - end + # example + allmails = nil + POP3.start( 'your.pop3.server', 110, + 'YourAccount, 'YourPassword' ) do |pop| + allmails = pop.mails.collect {|popmail| popmail.pop } + end : pop {|str| .... } - If pop() is called with block, it gives the block part strings of a mail. + gives the block part strings of a mail. - # usage example - - POP3.start( 'localhost', 110 ) do |pop3| - pop3.each_mail do |m| - m.pop do |str| - # do anything - end - end - end + # example + POP3.start( 'localhost', 110 ) {|pop3| + pop3.each_mail do |m| + m.pop do |str| + # do anything + end + end + } : header - This method fetches only mail header. + This method fetches only mail header. : top( lines ) - This method fetches mail header and 'lines' lines body. + This method fetches mail header and LINES lines of body. : delete -: delete! - This method deletes mail. + deletes mail on server. : size - size of mail(bytes) + mail size (bytes) : deleted? - true if mail was deleted + true if mail was deleted =end @@ -205,7 +313,12 @@ module Net pop.delete_all( &block ) end end - + + def auth_only( address = nil, port = nil, + account = nil, password = nil ) + new( address, port ).auth_only account, password + end + end @@ -215,6 +328,18 @@ module Net @apop = false end + def auth_only( account = nil, password = nil ) + begin + connect + @active = true + @command.auth address, port + @command.quit + ensure + @active = false + disconnect + end + end + attr :mails def each_mail( &block ) @@ -225,6 +350,7 @@ module Net alias each each_mail def delete_all + io_check @mails.each do |m| yield m if block_given? m.delete unless m.deleted? @@ -247,23 +373,20 @@ module Net (@apop ? type.apop_command_type : type.command_type).new(sock) end - def do_start( acnt, pwd ) - @command.auth( acnt, pwd ) + def do_start( account, password ) + @command.auth account, password - @mails = [] + mails = [] mtype = type.mail_type @command.list.each_with_index do |size,idx| - if size then - @mails.push mtype.new( idx, size, @command ) - end + mails.push mtype.new(idx, size, @command) if size end - @mails.freeze + @mails = mails.freeze end def io_check - if not @socket or @socket.closed? then - raise IOError, 'pop session is not opened yet' - end + (not @socket or @socket.closed?) and + raise IOError, 'pop session is not opened yet' end end @@ -359,8 +482,9 @@ module Net critical { getok 'LIST' @socket.read_pendlist do |line| - num, siz = line.split( / +/o ) - arr[ num.to_i ] = siz.to_i + m = /\A(\d+)[ \t]+(\d+)/.match(line) or + raise BadResponse, "illegal response: #{line}" + arr[ m[1].to_i ] = m[2].to_i end } arr @@ -376,26 +500,26 @@ module Net def top( num, lines = 0, dest = '' ) critical { getok sprintf( 'TOP %d %d', num, lines ) - @socket.read_pendstr( dest ) + @socket.read_pendstr dest } end def retr( num, dest = '', &block ) critical { - getok sprintf( 'RETR %d', num ) - @socket.read_pendstr( dest, &block ) + getok sprintf('RETR %d', num) + @socket.read_pendstr dest, &block } end def dele( num ) critical { - getok sprintf( 'DELE %d', num ) + getok sprintf('DELE %d', num) } end def uidl( num ) critical { - getok( sprintf 'UIDL %d', num ).msg.split(' ')[1] + getok( sprintf('UIDL %d', num) ).msg.split(' ')[1] } end @@ -436,17 +560,16 @@ module Net def initialize( sock ) rep = super( sock ) - m = /<.+>/.match( rep.msg ) - unless m then - raise ProtoAuthError, "This is not APOP server: can't login" - end + m = /<.+>/.match( rep.msg ) or + raise ProtoAuthError, "not APOP server: cannot login" @stamp = m[0] end def auth( account, pass ) critical { @socket.writeline sprintf( 'APOP %s %s', - account, MD5.new(@stamp + pass).hexdigest ) + account, + MD5.new(@stamp + pass).hexdigest ) check_reply_auth } end |