模块 OpenURI::OpenRead

OpenURI::OpenRead#open 为 URI::HTTP 和 URI::FTP 提供 'open' 功能。

OpenURI::OpenRead#open 接受可选的 3 个参数：

OpenURI::OpenRead#open([mode [, perm]] [, options]) [{|io| ... }]

OpenURI::OpenRead#open 如果没有给定块，则返回一个类似 IO 的对象。否则，它会生成 IO 对象并返回块的值。IO 对象使用 OpenURI::Meta 进行扩展。

mode 和 perm 与 Kernel#open 相同。

但是，mode 必须是读取模式，因为 OpenURI::OpenRead#open 尚不支持写入模式。此外，perm 被忽略，因为它仅对文件创建有意义。

options 必须是一个哈希。

每个带有字符串键的选项都会为 HTTP 指定额外的头部字段。即，对于没有 HTTP 代理的 FTP，它将被忽略。

哈希可能包含其他选项，其中键是符号

:proxy

概要

:proxy => "http://proxy.foo.com:8000/"
:proxy => URI.parse("http://proxy.foo.com:8000/")
:proxy => true
:proxy => false
:proxy => nil

如果指定了 :proxy 选项，则该值应为 String、URI、布尔值或 nil。

当给定 String 或 URI 时，它被视为代理 URI。

当给定 true 或未指定选项本身时，将检查环境变量 ‘scheme_proxy’。‘scheme’ 被 ‘http’、‘https’ 或 ‘ftp’ 替换。

当给定 false 或 nil 时，环境变量将被忽略，连接将直接与服务器建立。

:proxy_http_basic_authentication

概要

:proxy_http_basic_authentication =>
  ["http://proxy.foo.com:8000/", "proxy-user", "proxy-password"]
:proxy_http_basic_authentication =>
  [URI.parse("http://proxy.foo.com:8000/"),
   "proxy-user", "proxy-password"]

如果指定了 :proxy 选项，则该值应为包含 3 个元素的数组。它应包含一个代理 URI、一个代理用户名和一个代理密码。代理 URI 应该是 String、URI 或 nil。代理用户名和密码应该是 String。

如果为代理 URI 给定 nil，则此选项将被忽略。

如果指定了 :proxy 和 :proxy_http_basic_authentication，则会引发 ArgumentError。

:http_basic_authentication

概要

:http_basic_authentication=>[user, password]

如果指定了 :http_basic_authentication，则该值应为包含 2 个字符串的数组：用户名和密码。它用于 RFC 2617 定义的 HTTP 基本身份验证。

:content_length_proc

概要

:content_length_proc => lambda {|content_length| ... }

如果指定了 :content_length_proc 选项，则在开始实际传输之前调用该选项值过程。它接受一个参数，即预期的内容长度（以字节为单位）。

如果通过 HTTP 重定向执行了两个或多个传输，则该过程仅为最后一次传输调用一次。

当预期内容长度未知时，将使用 nil 调用该过程。当 HTTP 响应没有 Content-Length 头部时，会发生这种情况。

:progress_proc

概要

:progress_proc => lambda {|size| ...}

如果指定了 :progress_proc 选项，则每次 ‘open’ 从网络获取内容片段时，都会使用一个参数调用该 proc。参数 size 是累积传输的大小（以字节为单位）。

如果通过 HTTP 重定向执行了两个或多个传输，则该过程仅为最后一次传输调用一次。

:progress_proc 和 :content_length_proc 旨在用于进度条。例如，可以使用 Ruby/ProgressBar 实现如下。

pbar = nil
open("http://...",
  :content_length_proc => lambda {|t|
    if t && 0 < t
      pbar = ProgressBar.new("...", t)
      pbar.file_transfer_mode
    end
  },
  :progress_proc => lambda {|s|
    pbar.set s if pbar
  }) {|f| ... }

:read_timeout

概要

:read_timeout=>nil     (no timeout)
:read_timeout=>10      (10 second)

:read_timeout 选项指定 HTTP 连接读取的超时时间。

:open_timeout

概要

:open_timeout=>nil     (no timeout)
:open_timeout=>10      (10 second)

:open_timeout 选项指定 HTTP 连接打开的超时时间。

:ssl_ca_cert

概要

:ssl_ca_cert=>filename or an Array of filenames

:ssl_ca_cert 用于为 SSL 指定 CA 证书。如果给定此选项，则不使用默认证书。

:ssl_verify_mode

概要

:ssl_verify_mode=>mode

:ssl_verify_mode 用于指定 openssl 验证模式。

:ssl_min_version

概要

:ssl_min_version=>:TLS1_2

:ssl_min_version 选项指定允许的最小 SSL/TLS 协议版本。另请参见 OpenSSL::SSL::SSLContext#min_version=。

:ssl_max_version

概要

:ssl_max_version=>:TLS1_2

:ssl_max_version 选项指定允许的最大 SSL/TLS 协议版本。另请参见 OpenSSL::SSL::SSLContext#max_version=。

:ftp_active_mode

概要

:ftp_active_mode=>bool

:ftp_active_mode => true 用于使 ftp 处于主动模式。Ruby 1.9 默认使用被动模式。请注意，在 Ruby 1.8 或更早版本中，主动模式是默认模式。

:redirect

概要

:redirect=>bool

:redirect 默认为 true。:redirect => false 用于禁用所有 HTTP 重定向。

在重定向时引发 OpenURI::HTTPRedirect 异常。使用 true 也意味着允许在 http 和 ftp 之间进行重定向。

:max_redirects

概要

:max_redirects=>int

在引发 OpenURI::TooManyRedirects 之前允许的 HTTP 重定向次数。默认值为 64。

:request_specific_fields

概要

:request_specific_fields => {}
:request_specific_fields => lambda {|url| ...}

:request_specific_fields 选项允许指定随 HTTP 请求发送的自定义头部字段。它可以作为 Hash 或 Proc 传递，该 Proc 在每个请求上进行评估并返回头部字段的 Hash。

如果提供了 Hash，它仅为初始请求指定头部，并且这些头部不会在重定向时发送。

如果提供了 Proc，它将为每个请求（包括重定向）执行，从而允许基于请求 URL 进行动态头部自定义。重要的是 Proc 返回一个 Hash。并且此 Hash 指定要随请求发送的头部。

Hash 示例

URI.open("http://...",
         request_specific_fields: {"Authorization" => "token dummy"}) {|f| ... }

Proc 示例

URI.open("http://...",
         request_specific_fields: lambda { |uri|
           if uri.host == "example.com"
             {"Authorization" => "token dummy"}
           else
             {}
           end
         }) {|f| ... }

# File open-uri.rb, line 804
def open(*rest, &block)
  OpenURI.open_uri(self, *rest, &block)
end

OpenURI::OpenRead#read([ options ]) 读取 self 引用的内容，并将内容作为字符串返回。该字符串使用 OpenURI::Meta 进行扩展。参数 options 与 OpenURI::OpenRead#open 相同。

# File open-uri.rb, line 812
def read(options={})
  self.open(options) {|f|
    str = f.read
    Meta.init str, f
    str
  }
end