class Net::IMAP::FetchData

Net::IMAP::FetchData 表示 FETCH 响应的内容。Net::IMAP#fetch 和 Net::IMAP#uid_fetch 都返回一个 FetchData 对象数组。

获取属性¶ ↑

有关标准获取响应数据项的完整描述，请参阅 [IMAP4rev1 §7.4.2] 和 [IMAP4rev2 §7.5.2]，以及 Net::IMAP 中的消息信封和主体结构获取其他相关的 RFC。

静态获取数据项¶ ↑

大多数消息属性是静态的，对于给定的 (服务器、帐户、邮箱、UIDVALIDITY、UID) 元组，绝不能更改。

IMAP4rev1 和 IMAP4rev2 定义的静态获取数据项是

"UID" — 请参阅 uid。
"BODY" — 请参阅 body。
"BODY[#{section_spec}]", "BODY[#{section_spec}]<#{offset}>" — 请参阅 message, part, header, header_fields, header_fields_not, mime 和 text。
"BODYSTRUCTURE" — 请参阅 bodystructure。
"ENVELOPE" — 请参阅 envelope。
"INTERNALDATE" — 请参阅 internaldate。
"RFC822.SIZE" — 请参阅 rfc822_size。

IMAP4rev2 从 BINARY 扩展 [RFC3516] 添加了其他获取项

"BINARY[#{part}]", "BINARY[#{part}]<#{offset}>" – 请参阅 binary。
"BINARY.SIZE[#{part}]" – 请参阅 binary_size。

IMAP4rev1 中的几个静态消息属性已过时，并已从 IMAP4rev2 中删除

"RFC822" — 请参阅 rfc822 或替换为 "BODY[]" 和 message。
"RFC822.HEADER" — 请参阅 rfc822_header 或替换为 "BODY[HEADER]" 和 header。
"RFC822.TEXT" — 请参阅 rfc822_text 或替换为 "BODY[TEXT]" 和 text。

Net::IMAP 支持以下扩展定义的静态属性

OBJECTID [RFC8474]
- "EMAILID" — 请参阅 emailid。
- "THREADID" — 请参阅 threadid。
X-GM-EXT-1 [非标准的 Gmail 扩展]
- "X-GM-MSGID" — 唯一消息 ID。通过 attr 访问。
- "X-GM-THRID" — 线程 ID。通过 attr 访问。

注意: 其他 IMAP 扩展中定义了其他静态字段，但 Net::IMAP 尚无法解析它们。

动态消息属性¶ ↑

某些消息属性可以动态更改，例如使用 STORE 命令。

IMAP4rev1 和 IMAP4rev2 定义的唯一动态消息属性是

"FLAGS" — 请参阅 flags。

Net::IMAP 支持以下扩展定义的动态属性

CONDSTORE [RFC7162]
- "MODSEQ" — 请参阅 modseq。
X-GM-EXT-1 [非标准的 Gmail 扩展]
- "X-GM-LABELS" — Gmail 标签。通过 attr 访问。

注意: 其他 IMAP 扩展中定义了其他动态字段，但 Net::IMAP 尚无法解析它们。

隐式设置 `\Seen` 和使用 `PEEK`¶ ↑

除非邮箱已作为只读打开，否则获取 BODY[#{section}] 或 BINARY[#{section}] 将隐式设置 \Seen 标志。为了避免这种情况，请改用 BODY.PEEK[#{section}] 或 BINARY.PEEK[#{section}] 进行获取。

请注意，数据将始终在没有 ".PEEK" 的情况下返回，即 BODY[#{specifier}] 或 BINARY[#{section}] 中。

公共实例方法

attr → hash 点击切换源

每个键指定一个消息属性，值是对应的数据项。标准数据项具有相应的访问器方法。每个属性类型的定义在其访问器上记录。

注意： seqno 不是消息属性。

# File net-imap-0.5.4/lib/net/imap/fetch_data.rb, line 119

attr_upcase → hash 点击切换源

attr 的转换，所有键都转换为大写。

标头字段名称保留大小写，但不区分大小写，因此 header_fields 和 header_fields_not 会使用此方法。

# File net-imap-0.5.4/lib/net/imap/fetch_data.rb, line 136
def attr_upcase; attr.transform_keys(&:upcase) end

binary(*part_nums, offset: nil) → string 或 nil 点击切换源

返回特定 MIME 部分的二进制表示形式，该部分已根据其 Content-Transfer-Encoding 解码。

有关 part_nums 和 offset 的描述，请参阅 part。

这与从 attr 获取 "BINARY[#{part_nums.join(".")}]" 或 "BINARY[#{part_nums.join(".")}]<#{offset}>" 的值相同。

服务器必须支持 IMAP4rev2 或 BINARY 扩展 [RFC3516]。

另请参阅：binary_size, mime

# File net-imap-0.5.4/lib/net/imap/fetch_data.rb, line 430
def binary(*part_nums, offset: nil)
  attr[section_attr("BINARY", part_nums, offset: offset)]
end

binary_size(*part_nums) → integer 或 nil 点击切换源

返回特定 MIME 部分的解码大小（在响应 BINARY 获取请求时预期的大小）。

有关 part_nums 的描述，请参阅 part。

这与从 attr 获取 "BINARY.SIZE[#{part_nums.join(".")}]" 的值相同。

服务器必须支持 IMAP4rev2 或 BINARY 扩展 [RFC3516]。

另请参阅：binary, mime

# File net-imap-0.5.4/lib/net/imap/fetch_data.rb, line 451
def binary_size(*part_nums)
  attr[section_attr("BINARY.SIZE", part_nums)]
end

body → body structure 或 nil 点击切换源

返回 bodystructure 的另一种形式，不包含任何扩展数据。

这与从 attr 获取 "BODY" 的值相同。

注意: 使用 message, part, header, header_fields, header_fields_not, text, 或 mime 来检索 BODY[#{section_spec}] 属性。

# File net-imap-0.5.4/lib/net/imap/fetch_data.rb, line 148
def body; attr["BODY"] end

body_structure()

别名: bodystructure

bodystructure → BodyStructure 结构或 nil 点击切换源

一个 BodyStructure 对象，用于描述消息（如果已获取）。

这与从 attr 获取 "BODYSTRUCTURE" 的值相同。

# File net-imap-0.5.4/lib/net/imap/fetch_data.rb, line 310
def bodystructure; attr["BODYSTRUCTURE"] end

别名也为: body_structure

emailid → string 或 nil 点击切换源

一个 ObjectID，唯一标识单个消息的不可变内容。

在 COPY 或 MOVE 命令之后，服务器必须为源消息和目标消息返回相同的 EMAILID。但是，具有相同 EMAILID 的不同消息可能具有不同的可变属性，例如标志。

这与从 attr 获取 "EMAILID" 的值相同。

服务器必须支持 OBJECTID 扩展 [RFC8474]。

# File net-imap-0.5.4/lib/net/imap/fetch_data.rb, line 484
def emailid; attr["EMAILID"] end

envelope → Envelope 或 nil 点击切换源

一个 Envelope 对象，用于描述消息的信封结构。有关信封结构属性的描述，请参阅 Envelope 的文档。

这与从 attr 获取 "ENVELOPE" 的值相同。

# File net-imap-0.5.4/lib/net/imap/fetch_data.rb, line 321
def envelope; attr["ENVELOPE"] end

flags → 符号和字符串数组点击切换源

为此消息设置的标志数组。系统标志是由 String#capitalize 大写的符号。关键字标志是字符串，其大小写不会更改。

这与从 attr 获取 "FLAGS" 的值相同。

注意: FLAGS 字段是动态的，并且对于唯一标识的消息可以更改。

# File net-imap-0.5.4/lib/net/imap/fetch_data.rb, line 334
def flags; attr["FLAGS"] end

header(*part_nums, offset: nil) → string 或 nil 点击切换源

header(*part_nums, fields: names, offset: nil) → string 或 nil

header(*part_nums, except: names, offset: nil) → string 或 nil

消息或封装的 [RFC5322] 标头 [MIME-IMT] MESSAGE/RFC822 或 MESSAGE/GLOBAL 消息。

可以使用“mail” gem 解析标头。

有关 part_nums 和 offset 的描述，请参阅 part。

没有 `fields` 或 `except`¶ ↑

这与从 attr 获取以下值之一相同

BODY[HEADER]
BODY[HEADER]<#{offset}>
BODY[#{part_nums.join "."}.HEADER]"
BODY[#{part_nums.join "."}.HEADER]<#{offset}>"

使用 `fields`¶ ↑

当发送 fields 时，返回标头的一个子集，其中仅包含与列表中名称之一匹配的标头字段。

这与从 attr_upcase 获取以下值之一相同

正文[头部.字段 (#{names.join " "})]
正文[头部.字段 (#{names.join " "})]<#{offset}>
正文[#{part_nums.join "."}.头部.字段 (#{names.join " "})]
正文[#{part_nums.join "."}.头部.字段 (#{names.join " "})]<#{offset}>

另请参阅：header_fields

使用 `except`¶ ↑

当发送 except 时，返回头部的子集，该子集仅包含与列表中名称不匹配的头部字段。

这与从 attr_upcase 获取以下值之一相同

正文[头部.字段.非 (#{names.join " "})]
正文[头部.字段.非 (#{names.join " "})]<#{offset}>
正文[#{part_nums.join "."}.头部.字段.非 (#{names.join " "})]
正文[#{part_nums.join "."}.头部.字段.非 (#{names.join " "})]<#{offset}>

另请参阅：header_fields_not

# File net-imap-0.5.4/lib/net/imap/fetch_data.rb, line 234
def header(*part_nums, fields: nil, except: nil, offset: nil)
  fields && except and
    raise ArgumentError, "conflicting 'fields' and 'except' arguments"
  if fields
    text = "HEADER.FIELDS (%s)"     % [fields.join(" ").upcase]
    attr_upcase[body_section_attr(part_nums, text, offset: offset)]
  elsif except
    text = "HEADER.FIELDS.NOT (%s)" % [except.join(" ").upcase]
    attr_upcase[body_section_attr(part_nums, text, offset: offset)]
  else
    attr[body_section_attr(part_nums, "HEADER", offset: offset)]
  end
end

header_fields(*names, part: [], offset: nil) → string or nil 单击以切换源代码

当使用 fields: names 调用时，从 header 获取的结果。

# File net-imap-0.5.4/lib/net/imap/fetch_data.rb, line 252
def header_fields(first, *rest, part: [], offset: nil)
  header(*part, fields: [first, *rest], offset: offset)
end

header_fields_not(*names, part: [], offset: nil) → string or nil 单击以切换源代码

当使用 except: names 调用时，从 header 获取的结果。

# File net-imap-0.5.4/lib/net/imap/fetch_data.rb, line 260
def header_fields_not(first, *rest, part: [], offset: nil)
  header(*part, except: [first, *rest], offset: offset)
end

internal_date()

别名为：internaldate

internaldate → Time or nil 单击以切换源代码

服务器上消息的内部日期和时间。这不是 [RFC5322] 头部中的日期和时间，而是反映消息接收时间的日期和时间。

这类似于从 attr 获取 "INTERNALDATE" 的值。

注意: attr["INTERNALDATE"] 返回字符串，而此方法返回 Time 对象。

# File net-imap-0.5.4/lib/net/imap/fetch_data.rb, line 349
def internaldate
  attr["INTERNALDATE"]&.then { IMAP.decode_time _1 }
end

也别名为：internal_date

message(offset: bytes) → string or nil 单击以切换源代码

整个消息的 RFC5322 表达式，以字符串形式表示。

有关 offset 的描述，请参阅 part。

可以使用“mail” gem 解析 RFC5322 消息。

这与从 attr 获取 "BODY[]" 或 "BODY[]<#{offset}>" 的值相同。

另请参阅：header，text，和 mime。

# File net-imap-0.5.4/lib/net/imap/fetch_data.rb, line 164
def message(offset: nil) attr[body_section_attr(offset: offset)] end

mime(*part_nums) → string or nil 单击以切换源代码

mime(*part_nums, offset: bytes) → string or nil

如果已获取，则为消息部分的 [MIME-IMB] 头部。

有关 part_nums 和 offset 的描述，请参阅 part。

这与从 attr 获取 "BODY[#{part_nums}.MIME]" 或 "BODY[#{part_nums}.MIME]<#{offset}>" 的值相同。

另请参阅：message，header，和 text。

# File net-imap-0.5.4/lib/net/imap/fetch_data.rb, line 278
def mime(part, *subparts, offset: nil)
  attr[body_section_attr([part, *subparts], "MIME", offset: offset)]
end

modseq → Integer 单击以切换源代码

与此 IMAP 消息关联的修改序列号。

这与从 attr 获取 "MODSEQ" 的值相同。

服务器必须支持 CONDSTORE 扩展 [RFC7162]。

注意: MODSEQ 字段是动态的，并且对于唯一标识的消息可以更改。

# File net-imap-0.5.4/lib/net/imap/fetch_data.rb, line 467
def modseq; attr["MODSEQ"] end

part(*part_nums, offset: bytes) → string or nil 单击以切换源代码

特定 MIME 部分的字符串表示形式。

part_nums 形成 MIME 部分编号的路径，从 1 开始计数，这可以指定任意嵌套的部分，类似于 Array#dig。不使用 MIME 的消息，或不是多部分且不包含封装消息的 MIME 消息，仅具有部分 1。

如果给定了基于零的 offset，则返回的字符串是整个内容的子字符串，从该起始八位字节开始。这意味着 BODY[]<0> MAY 被截断，但 BODY[] 永远不会被截断。

这与从 attr 获取 "BODY[#{part_nums.join(".")}]" 或 "BODY[#{part_nums.join(".")}]<#{offset}>" 的值相同。

另请参阅：message，header，text，和 mime。

# File net-imap-0.5.4/lib/net/imap/fetch_data.rb, line 186
def part(index, *subparts, offset: nil)
  attr[body_section_attr([index, *subparts], offset: offset)]
end

rfc822 → String 单击以切换源代码

在语义上等同于没有参数的 message。

这与从 attr 获取 "RFC822" 的值相同。

注意: IMAP4rev2 弃用了 RFC822。

# File net-imap-0.5.4/lib/net/imap/fetch_data.rb, line 362
def rfc822; attr["RFC822"] end

rfc822_header → String 单击以切换源代码

在语义上等同于没有参数的 header。

这与从 attr 获取 "RFC822.HEADER" 的值相同。

注意: IMAP4rev2 弃用了 RFC822.HEADER。

# File net-imap-0.5.4/lib/net/imap/fetch_data.rb, line 392
def rfc822_header; attr["RFC822.HEADER"] end

rfc822_size -> Integer 单击以切换源代码

表示消息的 [RFC5322] 大小的数字。

这与从 attr 获取 "RFC822.SIZE" 的值相同。

注意: IMAP 最初是为较旧的 RFC822 标准开发的，因此 IMAP 中的几个提取项在其名称中包含“RFC822”。除了 RFC822.SIZE 之外，还有更现代的替代品；例如，RFC822.HEADER 的现代版本是 BODY.PEEK[HEADER]。在所有情况下，“RFC822”都应解释为对更新的 RFC5322 标准的引用。

# File net-imap-0.5.4/lib/net/imap/fetch_data.rb, line 381
def rfc822_size; attr["RFC822.SIZE"] end

也别名为：size

rfc822_text → String 单击以切换源代码

在语义上等同于没有参数的 text。

这与从 attr 获取 "RFC822.TEXT" 的值相同。

注意: IMAP4rev2 弃用了 RFC822.TEXT。

# File net-imap-0.5.4/lib/net/imap/fetch_data.rb, line 403
def rfc822_text; attr["RFC822.TEXT"] end

seqno → Integer 单击以切换源代码

消息序列号。

注意: 这永远不是唯一标识符 (UID)，即使对于 Net::IMAP#uid_fetch 结果也是如此。如果返回了 UID，则可以从 uid 中获取它。

# File net-imap-0.5.4/lib/net/imap/fetch_data.rb, line 108

size()

别名为：rfc822_size

text(*part_nums) → string or nil 单击以切换源代码

text(*part_nums, offset: bytes) → string or nil

如果已提取，则为消息或消息部分的文本正文，省略了 [RFC5322] 头部。

有关 part_nums 和 offset 的描述，请参阅 part。

这与从 attr 获取以下值之一相同

"正文[文本]",
"正文[文本]<#{offset}>",
"正文[#{section}.文本]"，或
"正文[#{section}.文本]<#{offset}>".

另请参阅：message，header，和 mime。

# File net-imap-0.5.4/lib/net/imap/fetch_data.rb, line 299
def text(*part, offset: nil)
  attr[body_section_attr(part, "TEXT", offset: offset)]
end

threadid → string or nil 单击以切换源代码

一个 ObjectID，唯一标识服务器认为应组合在一起的一组消息。

它通常基于 References、In-Reply-To 和 Subject 的某种组合，但具体实现由服务器实现决定。服务器应为相关消息返回相同的线程标识符，即使它们位于不同的邮箱中。

这与从 attr 获取 "THREADID" 的值相同。

服务器必须支持 OBJECTID 扩展 [RFC8474]。

# File net-imap-0.5.4/lib/net/imap/fetch_data.rb, line 501
def threadid; attr["THREADID"] end

uid → Integer 单击以切换源代码

表示消息唯一标识符的数字。

这与从 attr 获取 "UID" 的值相同。

# File net-imap-0.5.4/lib/net/imap/fetch_data.rb, line 410
def uid; attr["UID"] end

私有实例方法

body_section_attr(...) 单击以切换源代码

# File net-imap-0.5.4/lib/net/imap/fetch_data.rb, line 505
def body_section_attr(...) section_attr("BODY", ...) end

section_attr(attr, part = [], text = nil, offset: nil) 单击以切换源代码

# File net-imap-0.5.4/lib/net/imap/fetch_data.rb, line 507
def section_attr(attr, part = [], text = nil, offset: nil)
  spec = Array(part).flatten.map { Integer(_1) }
  spec << text if text
  spec = spec.join(".")
  if offset then "%s[%s]<%d>" % [attr, spec, Integer(offset)]
  else           "%s[%s]"     % [attr, spec]
  end
end

class Net::IMAP::FetchData

获取属性¶ ↑

静态获取数据项¶ ↑

动态消息属性¶ ↑

隐式设置 \Seen 和使用 PEEK¶ ↑

没有 fields 或 except¶ ↑

使用 fields¶ ↑

使用 except¶ ↑

隐式设置 `\Seen` 和使用 `PEEK`¶ ↑

没有 `fields` 或 `except`¶ ↑

使用 `fields`¶ ↑

使用 `except`¶ ↑