IMAP Extension for Referencing the Last SEARCH Result
updates
- rfc-3501 — INTERNET MESSAGE ACCESS PROTOCOL - VERSION 4rev1
Extracted elements (23)
A failed SEARCH RETURN (SAVE) with NO resets the search result variable to empty rather than preserving the previous value, to avoid ambiguity about which result "$" refers to in subsequent pipelined commands. Clients must reissue the SAVE command if they want to recover.
The extension avoids wasted bandwidth and round-trip delay by eliminating the need for the server to send a message list to the client, the client to reformat it, and resend it. It also enables pipelining of SEARCH with FETCH/STORE/COPY/EXPUNGE and allows server-side query optimization.
The "$" marker references either IMAP message sequences or UID sequences depending on context. A SEARCH (SAVE) result used with UID FETCH is interpreted as a UID sequence, while a UID SEARCH (SAVE) result used with FETCH is interpreted as a message sequence; servers must handle both directions.
When two independent SEARCH RETURN (SAVE) commands are pipelined (neither uses "$"), the server may execute them in any order. The result of the later-tagged command always overrides the earlier one, so the final value of "$" is determined by completion order.
A client supporting this extension MAY pipeline a SEARCH RETURN (SAVE) command with one or more commands using the "$" marker, as long as no ambiguity is created per RFC 3501 Section 5.5.
A SEARCH command with the SAVE result option that returns a NO tagged response MUST set the search result variable to the empty sequence. A SEARCH that returns BAD, or a successful SEARCH without SAVE, MUST NOT change the search result variable.
Even if the "$" marker contains the empty list of messages, it MUST be treated by all commands accepting message sets as a valid but non-matching list. For example, "FETCH $" returns a tagged OK with no FETCH responses.
If a server refuses to save a SEARCH (SAVE) result (e.g., due to internal limits), it MUST return a tagged NO response containing the NOTSAVED response code and set the search result variable to the empty sequence.
If the server sends a new UIDVALIDITY value while a mailbox is open, the search result variable MUST be reset to the empty list.
In the absence of any other SEARCH result option, the SAVE result option also suppresses any SEARCH response that would have otherwise been returned by the SEARCH command.
Servers implementing SEARCHRES MUST implement ESEARCH and conform to additional ESEARCH interaction requirements: when SAVE is combined with MIN or MAX only, "$" contains only the MIN/MAX message; when SAVE is combined with ALL and/or COUNT, "$" contains all found messages.
Upon successful completion of a SELECT or EXAMINE command (after the tagged OK response), the current search result variable MUST be reset to the empty sequence.
When a message listed in the search result variable is EXPUNGEd, it MUST be automatically removed from the list. If the server stores the list as message numbers, it MUST automatically adjust them when notifying the client about expunged messages.
When SAVE is combined with both MIN and MAX (and no other result options), "$" contains one or two messages as returned in the MIN/MAX return items. When COUNT or ALL is also present, "$" always contains all found messages.
When SEARCH RETURN (SAVE) is followed by a command using "$", the server MUST execute the two commands in the order they were received, as directed by Section 5.5 of RFC 3501, because of their direct dependency.
The "$" marker (seq-last-command) is a new token extending sequence-set in the IMAP ABNF. It represents the content of the search result variable and can be used wherever a message sequence set or UID sequence set is accepted.
The NOTSAVED response code is a new resp-text-code returned in a tagged NO response when the server refuses to save a SEARCH result, indicating the search result variable was not updated.
The SAVE result option instructs the server to store the result of a SEARCH or UID SEARCH command in an internal "search result variable". The client subsequently references this variable using the "$" marker in place of a message sequence set or UID sequence set.
The SEARCHRES extension is advertised via the "SEARCHRES" capability string in the CAPABILITY response. Any server implementing this extension MUST also implement the ESEARCH extension (RFC 4731).
This document registers the "SEARCHRES" capability in the IANA IMAP4 Capabilities Registry (http://www.iana.org/assignments/imap4-capabilities).
The extension requires the server to maintain additional per-connection state, which may be exploited to amplify Denial of Service attacks. Server implementations MAY limit the number of saved searches across all connections and return NOTSAVED when the limit is exceeded.
The search result variable transitions: initialized to empty on SELECT/EXAMINE; set to found messages on successful SEARCH RETURN (SAVE); reset to empty on SEARCH RETURN (SAVE) returning NO, UIDVALIDITY change, or mailbox close; messages removed individually on EXPUNGE.
The ABNF extensions are: capability =/ "SEARCHRES"; sequence-set =/ seq-last-command; seq-last-command = "$"; search-return-opt = "SAVE"; resp-text-code =/ "NOTSAVED". All alphabetic tokens are case-insensitive.