Network Working Group A. Melnikov
Request for Comments: 4731 Isode Ltd
Category: Standards Track D. Cridland
Inventure Systems Ltd
November 2006
Network Working Group A. Melnikov
Request for Comments: 4731 Isode Ltd
Category: Standards Track D. Cridland
Inventure Systems Ltd
November 2006
IMAP4 Extension to SEARCH Command for Controlling What Kind of Information Is Returned
IMAP4扩展到搜索命令，用于控制返回的信息类型
Status of This Memo
关于下段备忘
This document specifies an Internet standards track protocol for the Internet community, and requests discussion and suggestions for improvements. Please refer to the current edition of the "Internet Official Protocol Standards" (STD 1) for the standardization state and status of this protocol. Distribution of this memo is unlimited.
本文件规定了互联网社区的互联网标准跟踪协议，并要求进行讨论和提出改进建议。有关本协议的标准化状态和状态，请参考当前版本的“互联网官方协议标准”（STD 1）。本备忘录的分发不受限制。
Copyright Notice
版权公告
Copyright (C) The IETF Trust (2006).
版权所有（C）IETF信托基金（2006年）。
Abstract
摘要
This document extends IMAP (RFC 3501) SEARCH and UID SEARCH commands with several result options, which can control what kind of information is returned. The following result options are defined: minimal value, maximal value, all found messages, and number of found messages.
本文档使用几个结果选项扩展了IMAP（RFC 3501）搜索和UID搜索命令，这些选项可以控制返回的信息类型。定义了以下结果选项：最小值、最大值、所有找到的消息和找到的消息数。
Table of Contents
目录
1. Introduction ....................................................2
2. Conventions Used in This Document ...............................2
3. IMAP Protocol Changes ...........................................2
3.1. New SEARCH/UID SEARCH Result Options .......................2
3.2. Interaction with CONDSTORE extension .......................4
4. Formal Syntax ...................................................5
5. Security Considerations .........................................6
6. IANA Considerations .............................................6
7. Normative References ............................................6
8. Acknowledgments .................................................6
1. Introduction ....................................................2
2. Conventions Used in This Document ...............................2
3. IMAP Protocol Changes ...........................................2
3.1. New SEARCH/UID SEARCH Result Options .......................2
3.2. Interaction with CONDSTORE extension .......................4
4. Formal Syntax ...................................................5
5. Security Considerations .........................................6
6. IANA Considerations .............................................6
7. Normative References ............................................6
8. Acknowledgments .................................................6
[IMAPABNF] extended SEARCH and UID SEARCH commands with result specifiers (also known as result options), which can control what kind of information is returned.
[IMAPABNF]带有结果说明符（也称为结果选项）的扩展搜索和UID搜索命令，可以控制返回的信息类型。
A server advertising the ESEARCH capability supports the following result options: minimal value, maximal value, all found messages, and number of found messages. These result options allow clients to get SEARCH results in more convenient forms, while also saving bandwidth required to transport the results, for example, by finding the first unseen message or returning the number of unseen or deleted messages. Also, when a single MIN or a single MAX result option is specified, servers can optimize execution of SEARCHes.
发布ESEARCH功能的服务器支持以下结果选项：最小值、最大值、所有找到的消息和找到的消息数。这些结果选项允许客户端以更方便的形式获取搜索结果，同时还可以节省传输结果所需的带宽，例如，通过查找第一条未看到的消息或返回未看到或已删除消息的数量。此外，当指定单个最小值或单个最大值结果选项时，服务器可以优化搜索的执行。
In examples, "C:" and "S:" indicate lines sent by the client and server, respectively.
在示例中，“C:”和“S:”分别表示客户端和服务器发送的行。
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119 [KEYWORDS].
本文件中的关键词“必须”、“不得”、“必需”、“应”、“不应”、“应”、“不应”、“建议”、“可”和“可选”应按照RFC 2119[关键词]中所述进行解释。
The SEARCH/UID SEARCH commands are extended to allow for the following result options:
搜索/UID搜索命令已扩展，以允许以下结果选项：
MIN Return the lowest message number/UID that satisfies the SEARCH criteria.
MIN返回满足搜索条件的最低邮件编号/UID。
If the SEARCH results in no matches, the server MUST NOT include the MIN result option in the ESEARCH response; however, it still MUST send the ESEARCH response.
如果搜索结果不匹配，服务器不得在ESEARCH响应中包含MIN result选项；但是，它仍然必须发送ESEARCH响应。
MAX Return the highest message number/UID that satisfies the SEARCH criteria.
MAX返回满足搜索条件的最高邮件编号/UID。
If the SEARCH results in no matches, the server MUST NOT include the MAX result option in the ESEARCH response; however, it still MUST send the ESEARCH response.
如果搜索结果不匹配，服务器不得在ESEARCH响应中包含MAX result选项；但是，它仍然必须发送ESEARCH响应。
ALL Return all message numbers/UIDs that satisfy the SEARCH criteria. Unlike regular (unextended) SEARCH, the messages are always returned using the sequence-set syntax. A sequence-set representation may be more compact and can be used as is in a subsequent command that accepts sequence-set. Note, the client MUST NOT assume that messages/UIDs will be listed in any particular order.
ALL返回满足搜索条件的所有邮件编号/UID。与常规（未扩展）搜索不同，消息总是使用序列集语法返回。序列集表示可能更紧凑，可以在接受序列集的后续命令中使用。注意，客户端不得假设消息/UID将按任何特定顺序列出。
If the SEARCH results in no matches, the server MUST NOT include the ALL result option in the ESEARCH response; however, it still MUST send the ESEARCH response.
如果搜索结果不匹配，服务器不得在ESEARCH响应中包含ALL result选项；但是，它仍然必须发送ESEARCH响应。
COUNT Return number of the messages that satisfy the SEARCH criteria. This result option MUST always be included in the ESEARCH response.
计算满足搜索条件的邮件返回数。此结果选项必须始终包含在ESEARCH响应中。
If one or more result options described above are specified, the extended SEARCH command MUST return a single ESEARCH response [IMAPABNF], instead of the SEARCH response.
如果指定了上述一个或多个结果选项，则扩展搜索命令必须返回单个ESEARCH响应[IMAPABNF]，而不是搜索响应。
An extended UID SEARCH command MUST cause an ESEARCH response with the UID indicator present.
扩展UID搜索命令必须在UID指示器存在的情况下导致ESEARCH响应。
Note that future extensions to this document can allow servers to return multiple ESEARCH responses for a single extended SEARCH command. These extensions will have to describe how results from multiple ESEARCH responses are to be amalgamated.
请注意，此文档的未来扩展允许服务器为单个扩展搜索命令返回多个ESEARCH响应。这些扩展必须描述如何合并多个ESEARCH响应的结果。
If the list of result options is empty, that requests the server to return an ESEARCH response instead of the SEARCH response. This is equivalent to "(ALL)".
如果结果选项列表为空，则请求服务器返回ESEARCH响应而不是搜索响应。这相当于“（全部）”。
Example: C: A282 SEARCH RETURN (MIN COUNT) FLAGGED
SINCE 1-Feb-1994 NOT FROM "Smith"
S: * ESEARCH (TAG "A282") MIN 2 COUNT 3
S: A282 OK SEARCH completed
Example: C: A282 SEARCH RETURN (MIN COUNT) FLAGGED
SINCE 1-Feb-1994 NOT FROM "Smith"
S: * ESEARCH (TAG "A282") MIN 2 COUNT 3
S: A282 OK SEARCH completed
Example: C: A283 SEARCH RETURN () FLAGGED
SINCE 1-Feb-1994 NOT FROM "Smith"
S: * ESEARCH (TAG "A283") ALL 2,10:11
S: A283 OK SEARCH completed
Example: C: A283 SEARCH RETURN () FLAGGED
SINCE 1-Feb-1994 NOT FROM "Smith"
S: * ESEARCH (TAG "A283") ALL 2,10:11
S: A283 OK SEARCH completed
The following example demonstrates finding the first unseen message as returned in the UNSEEN response code on a successful SELECT command:
下面的示例演示如何在成功执行SELECT命令时查找在未看到的响应代码中返回的第一条未看到的消息：
Example: C: A284 SEARCH RETURN (MIN) UNSEEN
S: * ESEARCH (TAG "A284") MIN 4
S: A284 OK SEARCH completed
Example: C: A284 SEARCH RETURN (MIN) UNSEEN
S: * ESEARCH (TAG "A284") MIN 4
S: A284 OK SEARCH completed
The following example demonstrates that if the ESEARCH UID indicator is present, all data in the ESEARCH response is referring to UIDs; for example, the MIN result specifier will be followed by a UID.
以下示例说明，如果存在ESEARCH UID指示器，则ESEARCH响应中的所有数据都引用UID；例如，最小结果说明符后面将跟一个UID。
Example: C: A285 UID SEARCH RETURN (MIN MAX) 1:5000
S: * ESEARCH (TAG "A285") UID MIN 7 MAX 3800
S: A285 OK SEARCH completed
Example: C: A285 UID SEARCH RETURN (MIN MAX) 1:5000
S: * ESEARCH (TAG "A285") UID MIN 7 MAX 3800
S: A285 OK SEARCH completed
The following example demonstrates returning the number of deleted messages:
以下示例演示如何返回已删除邮件的数量：
Example: C: A286 SEARCH RETURN (COUNT) DELETED
S: * ESEARCH (TAG "A286") COUNT 15
S: A286 OK SEARCH completed
Example: C: A286 SEARCH RETURN (COUNT) DELETED
S: * ESEARCH (TAG "A286") COUNT 15
S: A286 OK SEARCH completed
When the server supports both the ESEARCH and the CONDSTORE [CONDSTORE] extension, and the client requests one or more result option described in section 3.1 together with the MODSEQ search criterion in the same SEARCH/UID SEARCH command, then the server MUST return the ESEARCH response containing the MODSEQ result option (described in the following paragraph) instead of the extended SEARCH response described in section 3.5 of [CONDSTORE].
当服务器同时支持ESEARCH和CONDSTORE[CONDSTORE]扩展，并且客户端在同一搜索/UID搜索命令中请求第3.1节所述的一个或多个结果选项以及MODSEQ搜索条件时，服务器必须返回包含MODSEQ结果选项的ESEARCH响应（在以下段落中描述）而不是[CONDSTORE]第3.5节中描述的扩展搜索响应。
If the SEARCH/UID SEARCH command contained a single MIN or MAX result option, the MODSEQ result option contains the mod-sequence for the found message. If the SEARCH/UID SEARCH command contained both MIN and MAX result options and no ALL/COUNT option, the MODSEQ result option contains the highest mod-sequence for the two returned messages. Otherwise the MODSEQ result option contains the highest mod-sequence for all messages being returned.
如果SEARCH/UID SEARCH命令包含单个MIN或MAX result选项，则MODSEQ result选项包含查找到的消息的mod序列。如果SEARCH/UID SEARCH命令同时包含MIN和MAX result选项，且不包含ALL/COUNT选项，则MODSEQ result选项包含两条返回消息的最高mod序列。否则，MODSEQ result选项包含返回的所有消息的最高mod序列。
Example: The following example demonstrates how Example 15 from [CONDSTORE] would look in the presence of one or more result option:
示例：以下示例演示了[CONDSTORE]中的示例15在存在一个或多个结果选项时的外观：
C: a1 SEARCH RETURN (MIN) MODSEQ "/flags/\\draft"
all 620162338
S: * ESEARCH (TAG "a1") MIN 2 MODSEQ 917162488
S: a1 OK Search complete
C: a1 SEARCH RETURN (MIN) MODSEQ "/flags/\\draft"
all 620162338
S: * ESEARCH (TAG "a1") MIN 2 MODSEQ 917162488
S: a1 OK Search complete
C: a2 SEARCH RETURN (MAX) MODSEQ "/flags/\\draft"
all 620162338
S: * ESEARCH (TAG "a2") MAX 23 MODSEQ 907162321
C: a2 SEARCH RETURN (MAX) MODSEQ "/flags/\\draft"
all 620162338
S: * ESEARCH (TAG "a2") MAX 23 MODSEQ 907162321
S: a2 OK Search complete
S:a2 OK搜索完成
C: a3 SEARCH RETURN (MIN MAX) MODSEQ "/flags/\\draft"
all 620162338
S: * ESEARCH (TAG "a3") MIN 2 MAX 23 MODSEQ 917162488
S: a3 OK Search complete
C: a3 SEARCH RETURN (MIN MAX) MODSEQ "/flags/\\draft"
all 620162338
S: * ESEARCH (TAG "a3") MIN 2 MAX 23 MODSEQ 917162488
S: a3 OK Search complete
C: a4 SEARCH RETURN (MIN COUNT) MODSEQ "/flags/\\draft"
all 620162338
S: * ESEARCH (TAG "a4") MIN 2 COUNT 10 MODSEQ 917162500
S: a4 OK Search complete
C: a4 SEARCH RETURN (MIN COUNT) MODSEQ "/flags/\\draft"
all 620162338
S: * ESEARCH (TAG "a4") MIN 2 COUNT 10 MODSEQ 917162500
S: a4 OK Search complete
The following syntax specification uses the Augmented Backus-Naur Form (ABNF) notation as specified in [ABNF].
以下语法规范使用[ABNF]中指定的增广Backus Naur Form（ABNF）表示法。
Non-terminals referenced but not defined below are as defined by [IMAP4], [CONDSTORE], or [IMAPABNF].
以下引用但未定义的非终端由[IMAP4]、[CONDSTORE]或[IMAPABNF]定义。
Except as noted otherwise, all alphabetic characters are case-insensitive. The use of upper or lowercase characters to define token strings is for editorial clarity only. Implementations MUST accept these strings in a case-insensitive fashion.
除非另有说明，否则所有字母字符都不区分大小写。使用大写或小写字符定义标记字符串仅为编辑目的。实现必须以不区分大小写的方式接受这些字符串。
capability =/ "ESEARCH"
能力=/“ESEARCH”
search-return-data = "MIN" SP nz-number /
"MAX" SP nz-number /
"ALL" SP sequence-set /
"COUNT" SP number
;; conforms to the generic
;; search-return-data syntax defined
;; in [IMAPABNF]
search-return-data = "MIN" SP nz-number /
"MAX" SP nz-number /
"ALL" SP sequence-set /
"COUNT" SP number
;; conforms to the generic
;; search-return-data syntax defined
;; in [IMAPABNF]
search-return-opt = "MIN" / "MAX" / "ALL" / "COUNT"
;; conforms to generic search-return-opt
;; syntax defined in [IMAPABNF]
search-return-opt = "MIN" / "MAX" / "ALL" / "COUNT"
;; conforms to generic search-return-opt
;; syntax defined in [IMAPABNF]
When the CONDSTORE [CONDSTORE] IMAP extension is also supported, the ABNF is updated as follows:
当CONDSTORE[CONDSTORE]IMAP扩展也受支持时，ABNF更新如下：
search-return-data =/ "MODSEQ" SP mod-sequence-value
;; mod-sequence-value is defined
;; in [CONDSTORE]
search-return-data =/ "MODSEQ" SP mod-sequence-value
;; mod-sequence-value is defined
;; in [CONDSTORE]
In the general case, the IMAP SEARCH/UID SEARCH commands can be CPU and/or IO intensive, and are seen by some as a potential attack point for denial of service attacks, so some sites/implementations even disable them entirely. This is quite unfortunate, as SEARCH command is one of the best examples demonstrating IMAP advantage over POP3.
在一般情况下，IMAP SEARCH/UID SEARCH命令可能是CPU和/或IO密集型命令，并且被一些人视为拒绝服务攻击的潜在攻击点，因此一些站点/实现甚至完全禁用它们。这是非常不幸的，因为SEARCH命令是展示IMAP优于POP3的最佳示例之一。
The ALL and COUNT return options don't change how SEARCH is working internally; they only change how information about found messages is returned. MIN and MAX SEARCH result options described in this document can lighten the load on IMAP servers that choose to optimize SEARCHes containing only one or both of them.
“全部”和“计数返回”选项不会更改搜索在内部的工作方式；它们只更改有关已找到邮件的信息的返回方式。本文档中介绍的最小和最大搜索结果选项可以减轻IMAP服务器上的负载，这些服务器选择优化只包含一个或两个搜索结果的搜索。
It is believed that this extension doesn't raise any additional security concerns not already discussed in [IMAP4].
据信，此扩展不会引起[IMAP4]中未讨论的任何其他安全问题。
IMAP4 capabilities are registered by publishing a standards track RFC or an IESG-approved experimental RFC. The registry is currently located at <http://www.iana.org/assignments/imap4-capabilities>.
IMAP4功能通过发布标准跟踪RFC或IESG批准的实验RFC进行注册。注册处目前位于<http://www.iana.org/assignments/imap4-capabilities>.
This document defines the ESEARCH IMAP capability, which IANA added to the registry.
本文档定义了IANA添加到注册表中的ESEARCH IMAP功能。
[KEYWORDS] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, March 1997.
[关键词]Bradner，S.，“RFC中用于表示需求水平的关键词”，BCP 14，RFC 2119，1997年3月。
[IMAP4] Crispin, M., "INTERNET MESSAGE ACCESS PROTOCOL - VERSION 4rev1", RFC 3501, March 2003.
[IMAP4]Crispin，M.，“互联网消息访问协议-版本4rev1”，RFC 35012003年3月。
[ABNF] Crocker, D. (Ed.) and P. Overell , "Augmented BNF for Syntax Specifications: ABNF", RFC 4234, October 2005.
[ABNF]Crocker，D.（编辑）和P.Overell，“语法规范的扩充BNF:ABNF”，RFC 42342005年10月。
[IMAPABNF] Melnikov, A. and C. Daboo, "Collected Extensions to IMAP4 ABNF", RFC 4466, April 2006..
[IMAPABNF]Melnikov，A.和C.Daboo，“IMAP4 ABNF的收集扩展”，RFC 4466，2006年4月。。
[CONDSTORE] Melnikov, A. and S. Hole, "IMAP Extension for Conditional STORE", RFC 4551, June 2006.
[CONDSTORE]Melnikov，A.和S.Hole，“条件存储的IMAP扩展”，RFC 45512006年6月。
Thanks to Michael Wener, Arnt Gulbrandsen, Cyrus Daboo, Mark Crispin, and Pete Maclean for comments and corrections.
感谢Michael Wener、Arnt Gulbrandsen、Cyrus Daboo、Mark Crispin和Pete Maclean的评论和更正。
Authors' Addresses
作者地址
Alexey Melnikov Isode Limited 5 Castle Business Village 36 Station Road Hampton, Middlesex, TW12 2BX UK
Alexey Melnikov Isode Limited 5 Castle Business Village 36 Station Road Hampton，Middlesex，TW12 2BX英国
EMail: Alexey.Melnikov@isode.com
EMail: Alexey.Melnikov@isode.com
Dave A. Cridland Inventure Systems Limited
戴夫A.克里德兰发明系统有限公司
EMail: dave.cridland@inventuresystems.co.uk
URL: http://invsys.co.uk/dave/
EMail: dave.cridland@inventuresystems.co.uk
URL: http://invsys.co.uk/dave/
Full Copyright Statement
完整版权声明
Copyright (C) The IETF Trust (2006).
版权所有（C）IETF信托基金（2006年）。
This document is subject to the rights, licenses and restrictions contained in BCP 78, and except as set forth therein, the authors retain all their rights.
本文件受BCP 78中包含的权利、许可和限制的约束，除其中规定外，作者保留其所有权利。
This document and the information contained herein are provided on an "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY, THE IETF TRUST, AND THE INTERNET ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
本文件及其包含的信息以“原样”为基础提供，贡献者、他/她所代表或赞助的组织（如有）、互联网协会、IETF信托基金和互联网工程任务组不承担任何明示或暗示的担保，包括但不限于任何保证，即使用本文中的信息不会侵犯任何权利，或对适销性或特定用途适用性的任何默示保证。
Intellectual Property
知识产权
The IETF takes no position regarding the validity or scope of any Intellectual Property Rights or other rights that might be claimed to pertain to the implementation or use of the technology described in this document or the extent to which any license under such rights might or might not be available; nor does it represent that it has made any independent effort to identify any such rights. Information on the procedures with respect to rights in RFC documents can be found in BCP 78 and BCP 79.
IETF对可能声称与本文件所述技术的实施或使用有关的任何知识产权或其他权利的有效性或范围，或此类权利下的任何许可可能或可能不可用的程度，不采取任何立场；它也不表示它已作出任何独立努力来确定任何此类权利。有关RFC文件中权利的程序信息，请参见BCP 78和BCP 79。
Copies of IPR disclosures made to the IETF Secretariat and any assurances of licenses to be made available, or the result of an attempt made to obtain a general license or permission for the use of such proprietary rights by implementers or users of this specification can be obtained from the IETF on-line IPR repository at http://www.ietf.org/ipr.
向IETF秘书处披露的知识产权副本和任何许可证保证，或本规范实施者或用户试图获得使用此类专有权利的一般许可证或许可的结果，可从IETF在线知识产权存储库获取，网址为http://www.ietf.org/ipr.
The IETF invites any interested party to bring to its attention any copyrights, patents or patent applications, or other proprietary rights that may cover technology that may be required to implement this standard. Please address the information to the IETF at ietf-ipr@ietf.org.
IETF邀请任何相关方提请其注意任何版权、专利或专利申请，或其他可能涵盖实施本标准所需技术的专有权利。请将信息发送至IETF的IETF-ipr@ietf.org.
Acknowledgement
确认
Funding for the RFC Editor function is currently provided by the Internet Society.
RFC编辑功能的资金目前由互联网协会提供。