Net::POP3 (Class)

In: net/pop.rb
Parent: Protocol

Class providing POP3 client functionality.

See documentation for the file pop.rb for examples of usage.

Methods

APOP   active?   apop?   auth_only   auth_only   command   default_port   delete_all   delete_all   each   each_mail   finish   foreach   inspect   mails   n_bytes   n_mails   new   read_timeout=   reset   set_debug_output   start   start   started?  

Constants

Revision = %q$Revision: 1.62 $.split[1]
POP = POP3
  class aliases
POPSession = POP3
POP3Session = POP3
APOPSession = APOP
  class aliases

Attributes

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.

Classes and Modules

Class Net::POP3::APOP
Class Net::POP3::POPMail

Public Class methods

The default port for POP3 connections, port 110

[Source]

# File net/pop.rb, line 199
    def POP3.default_port
      110
    end

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|
      ....
    }

[Source]

# 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

[Source]

# 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

[Source]

# 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)

[Source]

# 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
   }

[Source]

# 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.

[Source]

# 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

Public Instance methods

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.

[Source]

# File net/pop.rb, line 294
    def auth_only( account, password )
      raise IOError, 'opening already opened POP session' if started?
      start(account, password) {
        ;
      }
    end

Does this instance use APOP authentication?

[Source]

# File net/pop.rb, line 350
    def apop?
      @apop
    end

Provide human-readable stringification of class state.

[Source]

# 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) {
    ....
  }

[Source]

# File net/pop.rb, line 371
    def set_debug_output( arg )
      @debug_output = arg
    end

Set the read timeout.

[Source]

# File net/pop.rb, line 392
    def read_timeout=( sec )
      @command.socket.read_timeout = sec if @command
      @read_timeout = sec
    end

true if the POP3 session has started.

[Source]

# File net/pop.rb, line 398
    def started?
      @started
    end
active?()

Alias for started?

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.

[Source]

# 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

Finishes a POP3 session and closes TCP connection.

[Source]

# File net/pop.rb, line 447
    def finish
      raise IOError, 'POP session not started yet' unless started?
      do_finish
    end

[Source]

# 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.

[Source]

# 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.

[Source]

# 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.

[Source]

# 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

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.

[Source]

# File net/pop.rb, line 516
    def each_mail( &block )  # :yield: message

      mails().each(&block)
    end
each( )

Alias for 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.

[Source]

# 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

Resets the session. This clears all "deleted" marks from messages.

This method raises a POPError if an error occurs.

[Source]

# File net/pop.rb, line 546
    def reset
      command().rset
      mails().each do |m|
        m.instance_eval {
          @deleted = false
        }
      end
    end

[Validate]