# 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

default_port()

The default port for POP3 connections, port 110

[Source]

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

APOP( isapop )

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

foreach( address, port = nil, account = nil, password = nil, isapop = false ) {|message| ...}

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

delete_all( address, port = nil, account = nil, password = nil, isapop = false, &block )

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

auth_only( address, port = nil, account = nil, password = nil, isapop = false )

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

start( address, port = nil, account = nil, password = nil, isapop = false ) {|pop| ...}

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

new( addr, port = nil, isapop = false )

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

auth_only( account, password )

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

apop?()

Does this instance use APOP authentication?

[Source]

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

inspect()

Provide human-readable stringification of class state.

[Source]

    # File net/pop.rb, line 355
        def inspect
          "#<#{self.class} #{@address}:#{@port} open=#{@started}>"
        end

set_debug_output( arg )

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

read_timeout=( sec )

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

started?()

`true` if the POP3 session has started.

[Source]

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

active?()

Alias for started?

start( account, password ) {|pop| ...}

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

finish()

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

command()

[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

n_mails()

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

n_bytes()

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

mails()

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

each_mail( ) {|message| ...}

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

delete_all() {|message| ...}

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

reset()

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]