In: |
net/pop.rb
|
Parent: | Protocol |
Class providing POP3 client functionality.
See documentation for the file pop.rb for examples of usage.
Revision | = | %q$Revision: 1.62 $.split[1] |
POP | = | POP3 |
class aliases | ||
POPSession | = | POP3 |
POP3Session | = | POP3 |
APOPSession | = | APOP |
class aliases |
address | [R] | The address to connect to. |
open_timeout | [RW] | Seconds to wait until a connection is opened. If the POP3 object cannot open a connection within this time, it raises a TimeoutError exception. |
port | [R] | The port number to connect to. |
read_timeout | [R] | Seconds to wait until reading one block (by one read(1) call). If the POP3 object cannot complete a read() within this time, it raises a TimeoutError exception. |
Returns the APOP class if isapop is true; otherwise, returns the POP class. For example:
# Example 1 pop = Net::POP3::APOP($is_apop).new(addr, port) # Example 2 Net::POP3::APOP($is_apop).start(addr, port) {|pop| .... }
# File net/pop.rb, line 222 def POP3.APOP( isapop ) isapop ? APOP : POP3 end
Starts a POP3 session and iterates over each POPMail object, yielding it to the block. This method is equivalent to:
Net::POP3.start(address, port, account, password) {|pop| pop.each_mail do |m| yield m end }
This method raises a POPAuthenticationError if authentication fails.
# Typical usage Net::POP3.foreach('pop.example.com', 110, 'YourAccount', 'YourPassword') do |m| file.write m.pop m.delete if $DELETE end
# File net/pop.rb, line 245 def POP3.foreach( address, port = nil, account = nil, password = nil, isapop = false, &block ) # :yields: message start(address, port, account, password, isapop) {|pop| pop.each_mail(&block) } end
Starts a POP3 session and deletes all messages on the server. If a block is given, each POPMail object is yielded to it before being deleted.
This method raises a POPAuthenticationError if authentication fails.
# Example Net::POP3.delete_all('pop.example.com', 110, 'YourAccount', 'YourPassword') do |m| file.write m.pop end
# File net/pop.rb, line 265 def POP3.delete_all( address, port = nil, account = nil, password = nil, isapop = false, &block ) start(address, port, account, password, isapop) {|pop| pop.delete_all(&block) } end
Opens a POP3 session, attempts authentication, and quits.
This method raises POPAuthenticationError if authentication fails.
# Example 1: normal POP3 Net::POP3.auth_only('pop.example.com', 110, 'YourAccount', 'YourPassword') # Example 2: APOP Net::POP3.auth_only('pop.example.com', 110, 'YourAccount', 'YourPassword', true)
# File net/pop.rb, line 285 def POP3.auth_only( address, port = nil, account = nil, password = nil, isapop = false ) new(address, port, isapop).auth_only account, password end
Creates a new POP3 object and open the connection. Equivalent to Net::POP3.new(address, port, isapop).start(account, password)
If block is provided, yields the newly-opened POP3 object to it, and automatically closes it at the end of the session.
Typical usage:
Net::POP3.start(addr, port, account, password) {|pop| pop.each_mail do |m| file.write m.pop m.delete end }
# File net/pop.rb, line 320 def POP3.start( address, port = nil, account = nil, password = nil, isapop = false, &block ) # :yield: pop new(address, port, isapop).start(account, password, &block) end
Creates a new POP3 object. address is the hostname or ip address of your POP3 server. The optional port is the port to connect to; it defaults to 110. The optional isapop specifies whether this connection is going to use APOP authentication; it defaults to false. This method does not open the TCP connection.
# File net/pop.rb, line 332 def initialize( addr, port = nil, isapop = false ) @address = addr @port = port || self.class.default_port @apop = isapop @command = nil @socket = nil @started = false @open_timeout = 30 @read_timeout = 60 @debug_output = nil @mails = nil @n_mails = nil @n_bytes = nil end
Starts a pop3 session, attempts authentication, and quits. This method must not be called while POP3 session is opened. This method raises POPAuthenticationError if authentication fails.
# File net/pop.rb, line 294 def auth_only( account, password ) raise IOError, 'opening already opened POP session' if started? start(account, password) { ; } end
Provide human-readable stringification of class state.
# File net/pop.rb, line 355 def inspect "#<#{self.class} #{@address}:#{@port} open=#{@started}>" end
WARNING: This method causes a serious security hole. Use this method only for debugging.
Set an output stream for debugging.
# Example pop = Net::POP.new(addr, port) pop.set_debug_output $stderr pop.start(account, passwd) { .... }
# File net/pop.rb, line 371 def set_debug_output( arg ) @debug_output = arg end
Set the read timeout.
# File net/pop.rb, line 392 def read_timeout=( sec ) @command.socket.read_timeout = sec if @command @read_timeout = sec end
Starts a POP3 session.
When called with block, gives a POP3 object to the block and closes the session after block call finishes.
This method raises a POPAuthenticationError if authentication fails.
# File net/pop.rb, line 410 def start( account, password ) # :yield: pop raise IOError, 'POP session already started' if @started if block_given? begin do_start account, password return yield(self) ensure do_finish end else do_start account, password return self end end
# File net/pop.rb, line 463 def command raise IOError, 'POP session not opened yet' \ if not @socket or @socket.closed? @command end private :command # # POP protocol wrapper # # Returns the number of messages on the POP server. def n_mails return @n_mails if @n_mails @n_mails, @n_bytes = command().stat @n_mails end # Returns the total size in bytes of all the messages on the POP server. def n_bytes return @n_bytes if @n_bytes @n_mails, @n_bytes = command().stat @n_bytes end # Returns an array of Net::POPMail objects, representing all the # messages on the server. This array is renewed when the session # restarts; otherwise, it is fetched from the server the first time # this method is called (directly or indirectly) and cached. # # This method raises a POPError if an error occurs. def mails return @mails.dup if @mails if n_mails() == 0 # some popd raises error for LIST on the empty mailbox. @mails = [] return [] end @mails = command().list.map {|num, size| POPMail.new(num, size, self, command()) } @mails.dup end # Yields each message to the passed-in block in turn. # Equivalent to: # # pop3.mails.each do |popmail| # .... # end # # This method raises a POPError if an error occurs. def each_mail( &block ) # :yield: message mails().each(&block) end alias each each_mail # Deletes all messages on the server. # # If called with a block, yields each message in turn before deleting it. # # # Example # n = 1 # pop.delete_all do |m| # File.open("inbox/#{n}") {|f| # f.write m.pop # } # n += 1 # end # # This method raises a POPError if an error occurs. def delete_all # :yield: message mails().each do |m| yield m if block_given? m.delete unless m.deleted? end end # Resets the session. This clears all "deleted" marks from messages. # # This method raises a POPError if an error occurs. def reset command().rset mails().each do |m| m.instance_eval { @deleted = false } end end def set_all_uids #:nodoc: internal use only (called from POPMail#uidl) command().uidl.each do |num, uid| @mails.find {|m| m.number == num }.uid = uid end end end
Returns the number of messages on the POP server.
# File net/pop.rb, line 475 def n_mails return @n_mails if @n_mails @n_mails, @n_bytes = command().stat @n_mails end
Returns the total size in bytes of all the messages on the POP server.
# File net/pop.rb, line 482 def n_bytes return @n_bytes if @n_bytes @n_mails, @n_bytes = command().stat @n_bytes end
Returns an array of Net::POPMail objects, representing all the messages on the server. This array is renewed when the session restarts; otherwise, it is fetched from the server the first time this method is called (directly or indirectly) and cached.
This method raises a POPError if an error occurs.
# File net/pop.rb, line 494 def mails return @mails.dup if @mails if n_mails() == 0 # some popd raises error for LIST on the empty mailbox. @mails = [] return [] end @mails = command().list.map {|num, size| POPMail.new(num, size, self, command()) } @mails.dup end
Deletes all messages on the server.
If called with a block, yields each message in turn before deleting it.
# Example n = 1 pop.delete_all do |m| File.open("inbox/#{n}") {|f| f.write m.pop } n += 1 end
This method raises a POPError if an error occurs.
# File net/pop.rb, line 536 def delete_all # :yield: message mails().each do |m| yield m if block_given? m.delete unless m.deleted? end end