Network Working Group                                        A. MelnikovRequest for Comments: 4731                                     Isode LtdCategory: Standards Track                                    D. Cridland                                                   Inventure Systems Ltd                                                           November 2006           IMAP4 Extension to SEARCH Command for Controlling                  What Kind of Information Is ReturnedStatus 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.Copyright Notice   Copyright (C) The IETF Trust (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.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 .................................................6Melnikov & Cridland         Standards Track                     [Page 1]RFC 4731               IMAP4 Extension to SEARCH           November 20061.  Introduction   [IMAPABNF] extended SEARCH and UID SEARCH commands with result   specifiers (also known as result options), which can control what   kind of information is returned.   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.2.  Conventions Used in This Document   In examples, "C:" and "S:" indicate lines sent by the client and   server, respectively.   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].3.   IMAP Protocol Changes3.1.  New SEARCH/UID SEARCH Result Options   The SEARCH/UID SEARCH commands are extended to allow for the   following result options:      MIN         Return the lowest message number/UID that satisfies the SEARCH         criteria.         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.      MAX         Return the highest message number/UID that satisfies the SEARCH         criteria.         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.Melnikov & Cridland         Standards Track                     [Page 2]RFC 4731               IMAP4 Extension to SEARCH           November 2006      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.         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.      COUNT         Return number of the messages that satisfy the SEARCH criteria.         This result option MUST always be included in the ESEARCH         response.   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.   An extended UID SEARCH command MUST cause an ESEARCH response with   the UID indicator present.   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.   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)".      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   The following example demonstrates finding the first unseen message   as returned in the UNSEEN response code on a successful SELECT   command:Melnikov & Cridland         Standards Track                     [Page 3]RFC 4731               IMAP4 Extension to SEARCH           November 2006      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.      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 completed3.2.  Interaction with CONDSTORE extension   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].   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.   Example: The following example demonstrates how Example 15 from   [CONDSTORE] would look in the presence of one or more result option:         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 907162321Melnikov & Cridland         Standards Track                     [Page 4]