Class: Net::POP3
Relationships & Source Files | |
Extension / Inclusion / Inheritance Descendants | |
Subclasses:
|
|
Super Chains via Extension / Inclusion / Inheritance | |
Class Chain:
self,
Protocol
|
|
Instance Chain:
self,
Protocol
|
|
Inherits: |
Protocol
|
Defined in: | lib/net/pop.rb |
Overview
What is This Library?
This library provides functionality for retrieving email via POP3
, the Post Office Protocol version 3. For details of POP3
, see [RFC1939] (www.ietf.org/rfc/rfc1939.txt).
Examples
Retrieving Messages
This example retrieves messages from the server and deletes them on the server.
Messages are written to files named 'inbox/1', 'inbox/2', .… Replace 'pop.example.com' with your POP3
server address, and 'YourAccount' and 'YourPassword' with the appropriate account details.
require 'net/pop'
pop = Net::POP3.new('pop.example.com')
pop.start('YourAccount', 'YourPassword') # (1)
if pop.mails.empty?
puts 'No mail.'
else
i = 0
pop.each_mail do |m| # or "pop.mails.each ..." # (2)
File.open("inbox/#{i}", 'w') do |f|
f.write m.pop
end
m.delete
i += 1
end
puts "#{pop.mails.size} mails popped."
end
pop.finish # (3)
-
Access messages by using #each_mail and/or #mails.
-
Close POP session by calling #finish or use the block form of #start.
Shortened Code
The example above is very verbose. You can shorten the code by using some utility methods. First, the block form of .start can be used instead of .new, #start and #finish.
require 'net/pop'
Net::POP3.start('pop.example.com', 110,
'YourAccount', 'YourPassword') do |pop|
if pop.mails.empty?
puts 'No mail.'
else
i = 0
pop.each_mail do |m| # or "pop.mails.each ..."
File.open("inbox/#{i}", 'w') do |f|
f.write m.pop
end
m.delete
i += 1
end
puts "#{pop.mails.size} mails popped."
end
end
#delete_all is an alternative for #each_mail and #delete
.
require 'net/pop'
Net::POP3.start('pop.example.com', 110,
'YourAccount', 'YourPassword') do |pop|
if pop.mails.empty?
puts 'No mail.'
else
i = 1
pop.delete_all do |m|
File.open("inbox/#{i}", 'w') do |f|
f.write m.pop
end
i += 1
end
end
end
And here is an even shorter example.
require 'net/pop'
i = 0
Net::POP3.delete_all('pop.example.com', 110,
'YourAccount', 'YourPassword') do |m|
File.open("inbox/#{i}", 'w') do |f|
f.write m.pop
end
i += 1
end
Memory Space Issues
All the examples above get each message as one big string. This example avoids this.
require 'net/pop'
i = 1
Net::POP3.delete_all('pop.example.com', 110,
'YourAccount', 'YourPassword') do |m|
File.open("inbox/#{i}", 'w') do |f|
m.pop do |chunk| # get a message little by little.
f.write chunk
end
i += 1
end
end
Using APOP
The net/pop library supports .APOP authentication. To use .APOP, use the APOP class instead of the POP3
class. You can use the utility method, POP3
.APOP(). For example:
require 'net/pop'
# Use APOP authentication if $isapop == true
pop = Net::POP3.APOP($is_apop).new('apop.example.com', 110)
pop.start(YourAccount', 'YourPassword') do |pop|
# Rest of the code is the same.
end
Fetch Only Selected Mail Using 'UIDL' POP Command
If your POP server provides UIDL functionality, you can grab only selected mails from the POP server. e.g.
def need_pop?( id )
# determine if we need pop this mail...
end
Net::POP3.start('pop.example.com', 110,
'Your account', 'Your password') do |pop|
pop.mails.select { |m| need_pop?(m.unique_id) }.each do |m|
do_something(m.pop)
end
end
The POPMail#unique_id() method returns the unique-id of the message as a String. Normally the unique-id is a hash of the message.
Constant Summary
-
Revision =
svn revision of this library
%q$Revision$.split[1]
Class Attribute Summary
-
.use_ssl? ⇒ Boolean
readonly
returns
true
if .ssl_params is set.
Class Method Summary
- APOP(isapop)
-
.auth_only(address, port = nil, account = nil, password = nil, isapop = false)
Opens a
POP3
session, attempts authentication, and quits. -
.certs
returns the
:ca_file
or:ca_path
from .ssl_params -
.create_ssl_params(verify_or_params = {}, certs = nil)
Constructs proper parameters from arguments.
-
.default_pop3_port
The default port for
POP3
connections, port 110. -
.default_pop3s_port
The default port for POP3S connections, port 995.
-
.default_port
returns the port for
POP3
. -
.delete_all(address, port = nil, account = nil, password = nil, isapop = false, &block)
Starts a
POP3
session and deletes all messages on the server. -
.disable_ssl
Disable SSL for all new instances.
-
Net::POP.enable_ssl(params = {})
Enable SSL for all new instances.
-
.foreach(address, port = nil, account = nil, password = nil, isapop = false, &block)
Starts a
POP3
session and iterates over each POPMail object, yielding it to theblock
. -
.new(addr, port = nil, isapop = false) ⇒ POP3
constructor
Creates a new
POP3
object. -
.ssl_params
returns the SSL Parameters.
-
.start(address, port = nil, account = nil, password = nil, isapop = false, &block)
Creates a new
POP3
object and open the connection. -
.verify
returns whether verify_mode is enable from .ssl_params
Instance Attribute Summary
-
#open_timeout
rw
Seconds to wait until a connection is opened.
-
#read_timeout
rw
Seconds to wait until reading one block (by one read(1) call).
-
#read_timeout=(sec)
rw
Set the read timeout.
-
#address
readonly
The address to connect to.
-
#apop? ⇒ Boolean
readonly
Does this instance use .APOP authentication?
-
#started? ⇒ Boolean
(also: #active?)
readonly
true
if thePOP3
session has started. -
#use_ssl? ⇒ Boolean
readonly
does this instance use SSL?
Instance Method Summary
-
#auth_only(account, password)
Starts a pop3 session, attempts authentication, and quits.
-
#delete_all
Deletes all messages on the server.
-
#disable_ssl
Disable SSL for all new instances.
-
#each(&block)
Alias for #each_mail.
-
#each_mail(&block)
(also: #each)
Yields each message to the passed-in block in turn.
-
Net::POP
Enables SSL for this instance.
-
#finish
Finishes a
POP3
session and closes TCP connection. -
#inspect
Provide human-readable stringification of class state.
-
#logging(msg)
debugging output for
msg
-
#mails
Returns an array of POPMail objects, representing all the messages on the server.
-
#n_bytes
Returns the total size in bytes of all the messages on the POP server.
-
#n_mails
Returns the number of messages on the POP server.
-
#port
The port number to connect to.
-
#reset
Resets the session.
-
#set_debug_output(arg)
WARNING: This method causes a serious security hole.
-
#start(account, password)
Starts a
POP3
session.
Constructor Details
.new(addr, port = nil, isapop = false) ⇒ POP3
# File 'lib/net/pop.rb', line 418
def initialize(addr, port = nil, isapop = false) @address = addr @ssl_params = POP3.ssl_params @port = 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
Class Attribute Details
.use_ssl? ⇒ Boolean
(readonly)
returns true
if .ssl_params is set
# File 'lib/net/pop.rb', line 368
def POP3.use_ssl? return !@ssl_params.nil? end
Class Method Details
APOP(isapop)
# File 'lib/net/pop.rb', line 239
def POP3.APOP(isapop) isapop ? APOP : POP3 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: normal POP3
Net::POP3.auth_only('pop.example.com', 110,
'YourAccount', 'YourPassword')
Example: APOP
Net::POP3.auth_only('pop.example.com', 110,
'YourAccount', 'YourPassword', true)
.certs
returns the :ca_file
or :ca_path
from .ssl_params
# File 'lib/net/pop.rb', line 378
def POP3.certs return @ssl_params[:ca_file] || @ssl_params[:ca_path] end
.create_ssl_params(verify_or_params = {}, certs = nil)
Constructs proper parameters from arguments
# File 'lib/net/pop.rb', line 338
def POP3.create_ssl_params(verify_or_params = {}, certs = nil) begin params = verify_or_params.to_hash rescue NoMethodError params = {} params[:verify_mode] = verify_or_params if certs if File.file?(certs) params[:ca_file] = certs elsif File.directory?(certs) params[:ca_path] = certs end end end return params end
.default_pop3_port
The default port for POP3
connections, port 110
# File 'lib/net/pop.rb', line 211
def POP3.default_pop3_port 110 end
.default_pop3s_port
The default port for POP3S connections, port 995
# File 'lib/net/pop.rb', line 216
def POP3.default_pop3s_port 995 end
.default_port
returns the port for POP3
# File 'lib/net/pop.rb', line 206
def POP3.default_port default_pop3_port() 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
.disable_ssl
Disable SSL for all new instances.
# File 'lib/net/pop.rb', line 356
def POP3.disable_ssl @ssl_params = nil end
Net::POP.enable_ssl(params = {})
Enable SSL for all new instances. params
is passed to OpenSSL::SSLContext#set_params
.
# File 'lib/net/pop.rb', line 333
def POP3.enable_ssl(*args) @ssl_params = create_ssl_params(*args) end
.foreach(address, port = nil, account = nil, password = nil, isapop = false, &block)
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) do |pop|
pop.each_mail do |m|
yield m
end
end
This method raises a POPAuthenticationError if authentication fails.
Example
Net::POP3.foreach('pop.example.com', 110,
'YourAccount', 'YourPassword') do |m|
file.write m.pop
m.delete if $DELETE
end
.ssl_params
returns the SSL Parameters
see also .enable_ssl
# File 'lib/net/pop.rb', line 363
def POP3.ssl_params return @ssl_params end
.start(address, port = nil, account = nil, password = nil, isapop = false, &block)
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.
Example
Net::POP3.start(addr, port, account, password) do |pop|
pop.each_mail do |m|
file.write m.pop
m.delete
end
end
.verify
returns whether verify_mode is enable from .ssl_params
# File 'lib/net/pop.rb', line 373
def POP3.verify return @ssl_params[:verify_mode] end
Instance Attribute Details
#address (readonly)
The address to connect to.
# File 'lib/net/pop.rb', line 491
attr_reader :address
#apop? ⇒ Boolean
(readonly)
Does this instance use .APOP authentication?
# File 'lib/net/pop.rb', line 437
def apop? @apop end
#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 Net::OpenTimeout
exception. The default value is 30 seconds.
# File 'lib/net/pop.rb', line 501
attr_accessor :open_timeout
#read_timeout (rw)
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 Net::ReadTimeout
exception. The default value is 60 seconds.
# File 'lib/net/pop.rb', line 506
attr_reader :read_timeout
#read_timeout=(sec) (rw)
Set the read timeout.
# File 'lib/net/pop.rb', line 509
def read_timeout=(sec) @command.socket.read_timeout = sec if @command @read_timeout = sec end
#started? ⇒ Boolean
(readonly)
Also known as: #active?
true
if the POP3
session has started.
# File 'lib/net/pop.rb', line 515
def started? @started end
#use_ssl? ⇒ Boolean
(readonly)
does this instance use SSL?
# File 'lib/net/pop.rb', line 442
def use_ssl? return !@ssl_params.nil? end
Instance Method Details
#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.
#delete_all
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}") do |f|
f.write m.pop
end
n += 1
end
This method raises a POPError if an error occurs.
#disable_ssl
Disable SSL for all new instances.
# File 'lib/net/pop.rb', line 464
def disable_ssl @ssl_params = nil end
#each(&block)
Alias for #each_mail.
# File 'lib/net/pop.rb', line 669
alias each each_mail
#each_mail(&block) Also known as: #each
Net::POP
Enables SSL for this instance. Must be called before the connection is established to have any effect. params is port to establish the SSL connection on; Defaults to 995. params
(except :port
) is passed to OpenSSL::SSLContext#set_params
.
# File 'lib/net/pop.rb', line 453
def enable_ssl(verify_or_params = {}, certs = nil, port = nil) begin @ssl_params = verify_or_params.to_hash.dup @port = @ssl_params.delete(:port) || @port rescue NoMethodError @ssl_params = POP3.create_ssl_params(verify_or_params, certs) @port = port || @port end end
#finish
Finishes a POP3
session and closes TCP connection.
#inspect
Provide human-readable stringification of class state.
# File 'lib/net/pop.rb', line 469
def inspect "#<#{self.class} #{@address}:#{@port} open=#{@started}>" end
#logging(msg)
debugging output for msg
# File 'lib/net/pop.rb', line 712
def logging(msg) @debug_output << msg + "\n" if @debug_output end
#mails
#n_bytes
Returns the total size in bytes of all the messages on the POP server.
# File 'lib/net/pop.rb', line 631
def n_bytes return @n_bytes if @n_bytes @n_mails, @n_bytes = command().stat @n_bytes end
#n_mails
Returns the number of messages on the POP server.
# File 'lib/net/pop.rb', line 624
def n_mails return @n_mails if @n_mails @n_mails, @n_bytes = command().stat @n_mails end
#port
The port number to connect to.
# File 'lib/net/pop.rb', line 494
def port return @port || (use_ssl? ? POP3.default_pop3s_port : POP3.default_pop3_port) end
#reset
Resets the session. This clears all “deleted” marks from messages.
This method raises a POPError if an error occurs.
#set_debug_output(arg)
# File 'lib/net/pop.rb', line 486
def set_debug_output(arg) @debug_output = arg end
#start(account, password)
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.