class Net::POP3

这个库是做什么的？¶ ↑

这个库提供了通过 POP3（邮局协议版本 3）检索电子邮件的功能。有关 POP3 的详细信息，请参阅 [RFC1939] (www.ietf.org/rfc/rfc1939.txt)。

示例¶ ↑

检索消息¶ ↑

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

消息被写入名为 ‘inbox/1’、‘inbox/2’、……的文件。将 ‘pop.example.com’ 替换为您的 POP3 服务器地址，并将 ‘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)

调用 Net::POP3#start 并启动 POP 会话。
通过使用 POP3#each_mail 和/或 POP3#mails 访问消息。
通过调用 POP3#finish 关闭 POP 会话，或者使用 start 的块形式。

精简的代码¶ ↑

上面的例子非常冗长。您可以使用一些实用方法来缩短代码。首先，可以使用 Net::POP3.start 的块形式来代替 POP3.new、POP3#start 和 POP3#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

POP3#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($isapop).new('apop.example.com', 110)
pop.start('YourAccount', 'YourPassword') do |pop|
  # Rest of the code is the same.
end

使用 ‘UIDL’ POP 命令仅获取选定的邮件¶ ↑

如果您的 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

POPMail#unique_id() 方法将消息的唯一 ID 作为字符串返回。通常，唯一 ID 是消息的哈希值。

常量

VERSION: 此库的版本

属性

address[R]

要连接的地址。

open_timeout[RW]

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

read_timeout[R]

等待读取一个块（通过一个 read(1) 调用）的秒数。如果 POP3 对象无法在此时间内完成 read()，则会引发 Net::ReadTimeout 异常。默认值为 60 秒。

公共类方法

APOP(isapop) 点击切换源代码

如果 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 net-pop-0.1.2/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) 点击切换源代码

打开一个 POP3 会话，尝试身份验证，然后退出。

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

示例：普通 `POP3`¶ ↑

Net::POP3.auth_only('pop.example.com', 110,
                    'YourAccount', 'YourPassword')

示例：`APOP`¶ ↑

Net::POP3.auth_only('pop.example.com', 110,
                    'YourAccount', 'YourPassword', true)

# File net-pop-0.1.2/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() 点击切换源代码

从 POP3.ssl_params 返回 :ca_file 或 :ca_path

# File net-pop-0.1.2/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) 点击切换源代码

从参数构造正确的参数

# File net-pop-0.1.2/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() 点击切换源代码

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

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

default_pop3s_port() 点击切换源代码

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

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

default_port() 点击切换源代码

返回 POP3 的端口

# File net-pop-0.1.2/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) 点击切换源代码

启动一个 POP3 会话并删除服务器上的所有消息。如果给出了块，则在删除每个 POPMail 对象之前，会将其传递给该块。

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

示例¶ ↑

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

# File net-pop-0.1.2/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() 点击切换源代码

禁用所有新实例的 SSL。

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

Net::POP.enable_ssl(params = {}) 点击切换源代码

为所有新实例启用 SSL。params 被传递给 OpenSSL::SSLContext#set_params。

# File net-pop-0.1.2/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| ... } 点击切换源代码

启动一个 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 net-pop-0.1.2/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) 点击切换源代码

创建一个新的 POP3 对象。

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

可选的 port 是要连接的端口。

可选的 isapop 指定此连接是否将使用 APOP 身份验证；默认为 false。

此方法不打开 TCP 连接。

# File net-pop-0.1.2/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() 点击切换源代码

返回 SSL 参数

另请参阅 POP3.enable_ssl

# File net-pop-0.1.2/lib/net/pop.rb, line 362
def POP3.ssl_params
  return @ssl_params
end

start(address, port = nil, account = nil, password = nil, isapop = false) { |pop| ... } 点击切换源代码

创建一个新的 POP3 对象并打开连接。等效于

Net::POP3.new(address, port, isapop).start(account, password)

如果提供了 block，则将新打开的 POP3 对象传递给它，并在会话结束时自动关闭它。

示例¶ ↑

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

# File net-pop-0.1.2/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?() 点击切换源代码

如果设置了 POP3.ssl_params，则返回 true

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

verify() 点击切换源代码

从 POP3.ssl_params 返回是否启用了 verify_mode

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

公共实例方法

active?()

别名为：started?

apop?() 点击切换源代码

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

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

auth_only(account, password) 点击切换源代码

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

# File net-pop-0.1.2/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| ... } 点击切换源代码

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

如果使用块调用，则会在删除每个消息之前依次将其传递给该块。

示例¶ ↑

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

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

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

disable_ssl() 点击切换源代码

禁用所有新实例的 SSL。

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

each()

别名为：each_mail

each_mail() { |message| ... } 点击切换源代码

依次将每条消息传递给传入的块。等效于

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

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

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

也别名为：each

Net::POP#enable_ssl(params = {}) 点击以切换源代码

为此实例启用 SSL。必须在建立连接之前调用此方法才能生效。 params[:port] 是建立 SSL 连接的端口；默认为 995。params（除了 :port）被传递给 OpenSSL::SSLContext#set_params。

# File net-pop-0.1.2/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() 点击以切换源代码

结束一个 POP3 会话并关闭 TCP 连接。

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

inspect() 点击以切换源代码

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

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

logging(msg) 点击以切换源代码

用于 msg 的调试输出

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

mails() 点击以切换源代码

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

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

# File net-pop-0.1.2/lib/net/pop.rb, line 646
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() 点击以切换源代码

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

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

n_mails() 点击以切换源代码

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

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

port() 点击以切换源代码

要连接的端口号。

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

read_timeout=(sec) 点击以切换源代码

设置读取超时。

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

reset() 点击以切换源代码

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

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

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

set_debug_output(arg) 点击以切换源代码

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

为调试设置一个输出流。

示例¶ ↑

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

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

start(account, password) { |pop| ... } 点击以切换源代码

启动一个 POP3 会话。

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

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

# File net-pop-0.1.2/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?() 点击以切换源代码

如果 POP3 会话已启动，则为 true。

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

也别名为： active?

use_ssl?() 点击切换源代码

此实例是否使用 SSL？

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

class Net::POP3

这个库是做什么的？¶ ↑

示例¶ ↑

检索消息¶ ↑

精简的代码¶ ↑

内存空间问题¶ ↑

使用 APOP¶ ↑

使用 ‘UIDL’ POP 命令仅获取选定的邮件¶ ↑

示例：普通 POP3¶ ↑

示例：APOP¶ ↑

示例¶ ↑

示例¶ ↑

示例¶ ↑

示例¶ ↑

示例¶ ↑

使用 `APOP`¶ ↑

示例：普通 `POP3`¶ ↑

示例：`APOP`¶ ↑