Net::POP3

class Net::POP3

Parent:Protocol

这个图书馆是什么？

此库提供了通过POP3（邮局协议版本3）检索电子邮件的功能。有关POP3的详细信息，请参阅RFC1939。

例子

检索消息

本示例从服务器检索消息并在服务器上删除它们。

邮件将被写入名为“收件箱/ 1”，“收件箱/ 2”的文件中......用您的POP3服务器地址替换“pop.example.com”，并用适当的帐户详细信息替换“YourAccount”和“YourPassword”。

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)

致电＃开始并开始POP会话。

通过使用#each_mail和/或#mails访问消息。

通过调用#finish关闭POP会话或使用start的块形式。

缩短的代码

上面的例子非常详细。您可以通过使用某些实用程序方法来缩短代码。首先，:: start的块形式可以用来代替:: new，＃start和#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是each_mail和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

这是一个更简短的例子。

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

内存空间问题

以上所有示例都将每条消息都视为一个大字符串。这个例子避免了这一点。

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

使用APOP

net / pop库支持APOP认证。要使用APOP，请使用Net :: APOP类而不是Net :: POP3类。您可以使用实用程序方法Net :: POP3.APOP（）。例如：

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

如果您的POP服务器提供了UIDL功能，那么您只能从POP服务器获取选定的邮件。例如

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

Net :: POPMail＃unique_id方法以String形式返回消息的唯一标识。通常，唯一标识是消息的散列。

常量

调整

该库的 svn 修订版

属性

addressR

要连接的地址。

open_timeoutRW

秒等待连接打开。如果POP3对象在这段时间内无法打开连接，则会引发Net :: OpenTimeout异常。默认值是30秒。

read_timeoutR

秒等到读取一个块（通过一次读取（1）调用）。如果POP3对象在这段时间内无法完成读取（），则会引发Net :: ReadTimeout异常。默认值是60秒。

公共类方法

APOP(isapop) Show source

如果isapop为true，则返回APOP类; 否则，返回POP类。例如：

# Example 1
pop = Net::POP3::APOP($is_apop).new(addr, port)

# Example 2
Net::POP3::APOP($is_apop).start(addr, port) do |pop|
  ....
end

# File lib/net/pop.rb, line 238
def POP3.APOP(isapop)
  isapop ? APOP : POP3
end

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

打开POP3会话，尝试验证，然后退出。

如果身份验证失败，此方法将引发POPAuthenticationError。

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)

# File lib/net/pop.rb, line 305
def POP3.auth_only(address, port = nil,
                   account = nil, password = nil,
                   isapop = false)
  new(address, port, isapop).auth_only account, password
end

certs() Show source

returns the :ca_file or :ca_path from ::ssl_params

# File lib/net/pop.rb, line 377
def POP3.certs
  return @ssl_params[:ca_file] || @ssl_params[:ca_path]
end

create_ssl_params(verify_or_params = {}, certs = nil) Show source

根据参数构造适当的参数

# File lib/net/pop.rb, line 337
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() Show source

POP3连接的默认端口，端口110

# File lib/net/pop.rb, line 210
def POP3.default_pop3_port
  110
end

default_pop3s_port() Show source

POP3S连接的默认端口，端口995

# File lib/net/pop.rb, line 215
def POP3.default_pop3s_port
  995
end

default_port() Show source

返回POP3的端口

# File lib/net/pop.rb, line 205
def POP3.default_port
  default_pop3_port()
end

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

启动POP3会话并删除服务器上的所有消息。如果给出了一个块，则在删除之前，每个POPMail对象都被赋予它。

如果认证失败，此方法会引发POPAuthenticationError。

例

Net::POP3.delete_all('pop.example.com', 110,
                     'YourAccount', 'YourPassword') do |m|
  file.write m.pop
end

# File lib/net/pop.rb, line 283
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

disable_ssl() Show source

为所有新实例禁用 SSL。

# File lib/net/pop.rb, line 355
def POP3.disable_ssl
  @ssl_params = nil
end

Net::POP.enable_ssl(params = {}) Show source

Enable SSL for all new instances. params is passed to OpenSSL::SSLContext#set_params.

# File lib/net/pop.rb, line 332
def POP3.enable_ssl(*args)
  @ssl_params = create_ssl_params(*args)
end

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

启动一个POP3会话并遍历每个POPMail对象，并将其传递给block。这种方法相当于：

Net::POP3.start(address, port, account, password) do |pop|
  pop.each_mail do |m|
    yield m
  end
end

如果认证失败，此方法会引发POPAuthenticationError。

例

Net::POP3.foreach('pop.example.com', 110,
                  'YourAccount', 'YourPassword') do |m|
  file.write m.pop
  m.delete if $DELETE
end

# File lib/net/pop.rb, line 262
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

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

创建一个新的POP3对象。

address 是您的POP3服务器的主机名或IP地址。

可选port是要连接的端口。

可选项isapop指定此连接是否要使用APOP认证; 它默认为false。

这个方法并没有打开的TCP连接。

# File lib/net/pop.rb, line 417
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

ssl_params() Show source

返回SSL参数

例

Net::POP3.start(addr, port, account, password) do |pop|
  pop.each_mail do |m|
    file.write m.pop
    m.delete
  end
end

# File lib/net/pop.rb, line 401
def POP3.start(address, port = nil,
               account = nil, password = nil,
               isapop = false, &block)   # :yield: pop
  new(address, port, isapop).start(account, password, &block)
end

use_ssl?() Show source

true如果:: ssl_params 被设置，则返回

# File lib/net/pop.rb, line 367
def POP3.use_ssl?
  return !@ssl_params.nil?
end

verify() Show source

返回是否从:: ssl_params启用了verify_mode

# File lib/net/pop.rb, line 372
def POP3.verify
  return @ssl_params[:verify_mode]
end

公共实例方法

active?()

Alias for: started?

apop?() Show source

此实例是否使用 APOP 身份验证？

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

auth_only(account, password) Show source

启动pop3会话，尝试身份验证并退出。在打开POP3会话时不能调用此方法。如果身份验证失败，此方法将引发POPAuthenticationError。

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

delete_all() { |message| ... } Show source

删除服务器上的所有消息。

如果用块调用，则在删除它之前依次生成每条消息。

例

n = 1
pop.delete_all do |m|
  File.open("inbox/#{n}") do |f|
    f.write m.pop
  end
  n += 1
end

如果发生错误，此方法会引发 POPError。

# File lib/net/pop.rb, line 686
def delete_all # :yield: message
  mails().each do |m|
    yield m if block_given?
    m.delete unless m.deleted?
  end
end

disable_ssl() Show source

为所有新实例禁用SSL。

# File lib/net/pop.rb, line 463
def disable_ssl
  @ssl_params = nil
end

each()

Alias for: each_mail

each_mail() { |message| ... } Show source

依次将每个消息传递给传入的块。相当于：

pop3.mails.each do |popmail|
  ....
end

如果发生错误，此方法会引发POPError。

# File lib/net/pop.rb, line 664
def each_mail(&block)  # :yield: message
  mails().each(&block)
end

Also aliased as: each

Net::POP#enable_ssl(params = {}) Show source

为此实例启用SSL。必须在建立连接之前调用才能起作用。+ params +是建立SSL连接的端口; 默认为995. params（except：port）传递给OpenSSL :: SSLContext＃set_params。

# File lib/net/pop.rb, line 452
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() Show source

完成POP3会话并关闭TCP连接。

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

inspect() Show source

提供人类可读的类状态的字符串化。

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

logging(msg) Show source

调试输出 msg

# File lib/net/pop.rb, line 711
def logging(msg)
  @debug_output << msg + "\n" if @debug_output
end

mails() Show source

返回一个Net :: POPMail对象数组，表示服务器上的所有消息。当会话重新启动时，该阵列被更新; 否则，在第一次调用（直接或间接）和缓存该方法时从服务器获取它。

如果发生错误，此方法会引发POPError。

# File lib/net/pop.rb, line 642
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

n_bytes() Show source

返回POP服务器上所有消息的总大小（以字节为单位）。

# File lib/net/pop.rb, line 630
def n_bytes
  return @n_bytes if @n_bytes
  @n_mails, @n_bytes = command().stat
  @n_bytes
end

n_mails() Show source

返回 POP 服务器上的消息数量。

# File lib/net/pop.rb, line 623
def n_mails
  return @n_mails if @n_mails
  @n_mails, @n_bytes = command().stat
  @n_mails
end

port() Show source

The port number to connect to.

# File lib/net/pop.rb, line 493
def port
  return @port || (use_ssl? ? POP3.default_pop3s_port : POP3.default_pop3_port)
end

read_timeout=(sec) Show source

Set the read timeout.

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

reset() Show source

重置会话。这将清除消息中的所有“已删除”标记。

如果发生错误，此方法会引发POPError。

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

set_debug_output(arg) Show source

警告：此方法会导致严重的安全漏洞。使用此方法仅用于调试。

设置输出流以进行调试。

例

pop = Net::POP.new(addr, port)
pop.set_debug_output $stderr
pop.start(account, passwd) do |pop|
  ....
end

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

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

开始一个 POP3 会话。

当用块调用时，给块提供POP3对象，并在块调用完成后关闭会话。

如果认证失败，此方法会引发 POPAuthenticationError。

# File lib/net/pop.rb, line 526
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

started?() Show source

true 如果 POP3 会话已启动。

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

Also aliased as: active?

use_ssl?() Show source

does this instance use SSL?

# File lib/net/pop.rb, line 441
def use_ssl?
  return !@ssl_params.nil?
end