< draft-melnikov-imap-search-ret-02.txt   draft-melnikov-imap-search-ret-03.txt >
Internet Draft A. Melnikov Internet Draft A. Melnikov
Document: draft-melnikov-imap-search-ret Isode Ltd Document: draft-melnikov-imap-search-ret-03 Isode Ltd
Expires: April 2006 D. Cridland Expires: December 2006 D. Cridland
Inventure Systems Ltd Inventure Systems Ltd
October 2005 June 2006
IMAP4 extension to SEARCH command for controlling what kind of IMAP4 extension to SEARCH command for controlling what kind of
information is returned information is returned
draft-melnikov-imap-search-ret-02 draft-melnikov-imap-search-ret-03
Status of this Memo Status of this Memo
By submitting this Internet-Draft, each author represents that any By submitting this Internet-Draft, each author represents that any
applicable patent or other IPR claims of which he or she is aware applicable patent or other IPR claims of which he or she is aware
have been or will be disclosed, and any of which he or she becomes have been or will be disclosed, and any of which he or she becomes
aware will be disclosed, in accordance with Section 6 of BCP 79. aware will be disclosed, in accordance with Section 6 of BCP 79.
Internet-Drafts are working documents of the Internet Engineering Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF), its areas, and its working groups. Note that Task Force (IETF), its areas, and its working groups. Note that
skipping to change at line 43 skipping to change at line 43
http://www.ietf.org/shadow.html. http://www.ietf.org/shadow.html.
A revised version of this draft document will be submitted to the A revised version of this draft document will be submitted to the
RFC editor as a Standard Track RFC for the Internet Community. RFC editor as a Standard Track RFC for the Internet Community.
Discussion and suggestions for improvement are requested, and Discussion and suggestions for improvement are requested, and
should be sent to ietf-imapext@imc.org and/or lemonade@ietf.org. should be sent to ietf-imapext@imc.org and/or lemonade@ietf.org.
Distribution of this memo is unlimited. Distribution of this memo is unlimited.
Abstract Abstract
This document extends SEARCH and UID SEARCH commands with result This document extends IMAP (RFC 3501) SEARCH and UID SEARCH
specifier, which can control what kind of information is returned. commands with several result options, which can control what kind
Several result specifiers are defined: minimal value, maximal of information is returned. The following result options are
value, all found messages and number of found messages. A new defined: minimal value, maximal value, all found messages and
untagged response ESEARCH is also specified. number of found messages.
Table of Contents Table of Contents
1. Conventions Used in this Document 2 1. Conventions Used in this Document 2
2. Introduction 3 2. Introduction 3
3. IMAP Protocol Changes 3 3. IMAP Protocol Changes 3
3.1 SEARCH/UID SEARCH Commands 3 3.1 SEARCH/UID SEARCH Commands 3
4. Formal Syntax 6 4. Formal Syntax 6
5. Security Considerations 7 5. Security Considerations 7
6. IANA Considerations 7 6. IANA Considerations 7
skipping to change at line 74 skipping to change at line 74
11. Intellectual Property 9 11. Intellectual Property 9
12. Appendix A. Editorial. 9 12. Appendix A. Editorial. 9
12.1 Change Log 9 12.1 Change Log 9
12.2 Open Issues for Discussion 10 12.2 Open Issues for Discussion 10
1. Conventions Used in this Document 1. Conventions Used in this Document
In examples, "C:" and "S:" indicate lines sent by the client and In examples, "C:" and "S:" indicate lines sent by the client and
server respectively. server respectively.
The key words "MUST", "MUST NOT", "SHOULD", "SHOULD NOT", and "MAY" The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
in this document are to be interpreted as defined in "Key words for "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in
use in RFCs to Indicate Requirement Levels" [KEYWORDS]. this document are to be interpreted as described in RFC 2119 [KEYWORDS].
<<Editorial comments and questions are enclosed like this>> <<Editorial comments and questions are enclosed like this>>
2. Introduction 2. Introduction
This document extends SEARCH and UID SEARCH commands with result [IMAPABNF] extended SEARCH and UID SEARCH commands with result
specifiers (also known as return options), which can control what specifiers (also known as result options), which can control what
kind of information is returned. Several result specifiers are kind of information is returned.
defined: minimal value, maximal value, all found messages and
number of found messages.
A new response ESEARCH is also specified, which replaces the SEARCH
response.
The extension described in this document allows clients to get A server advertising the X-DRAFT-I02-ESEARCH <<fix before
results for SEARCH requests in a more convenient form, while also publication>> capability supports the following result options:
saving bandwidth required to transport the results, for example minimal value, maximal value, all found messages and number of
finding the first unseen message or returning the number of unseen found messages. These result options allows clients to get SEARCH
or deleted messages. Also, when a single MIN or a single MAX return results in more convenient forms, while also saving bandwidth
option is specified, servers can optimize execution of SEARCHes. required to transport the results, for example 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.
3. IMAP Protocol Changes 3. IMAP Protocol Changes
3.1 SEARCH/UID SEARCH Commands 3.1 New SEARCH/UID SEARCH result options
Arguments: OPTIONAL result specifier
OPTIONAL [CHARSET] specification
searching criteria (one or more)
Responses: REQUIRED untagged response: SEARCH or ESEARCH
Result: OK - search completed
NO - search error: can't search that [CHARSET] or
criteria
BAD - command unknown or arguments invalid
This section updates definition of the SEARCH command described in
section 6.4.4 of [IMAP4].
The SEARCH/UID SEARCH command is extended to allow for result The SEARCH/UID SEARCH commands are extended to allow for the
options. This document defines 4 search result options: following result options:
MIN MIN
Return the lowest message number/UID that satisfies the Return the lowest message number/UID that satisfies the
SEARCH criteria. SEARCH criteria.
If the SEARCH results in no matches, the server MUST NOT If the SEARCH results in no matches, the server MUST NOT
include the MIN result option in the ESEARCH response, include the MIN result option in the ESEARCH response,
however it still MUST send the ESEARCH response. however it still MUST send the ESEARCH response.
MAX MAX
Return the highest message number/UID that satisfies the Return the highest message number/UID that satisfies the
skipping to change at line 200 skipping to change at line 184
S: * ESEARCH (TAG "A285") UID MIN 7 MAX 3800 S: * ESEARCH (TAG "A285") UID MIN 7 MAX 3800
S: A285 OK SEARCH completed S: A285 OK SEARCH completed
The following example demonstrates returning the number of deleted The following example demonstrates returning the number of deleted
messages: messages:
Example: C: A286 SEARCH RETURN (COUNT) DELETED Example: C: A286 SEARCH RETURN (COUNT) DELETED
S: * ESEARCH (TAG "A286") COUNT 15 S: * ESEARCH (TAG "A286") COUNT 15
S: A286 OK SEARCH completed S: A286 OK SEARCH completed
3.2 Interaction with CONDSTORE extension
When the server supports both the X-DRAFT-I02-ESEARCH <<fix before
publication>> 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 907162321
S: a2 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
4. Formal Syntax 4. Formal Syntax
The following syntax specification uses the Augmented Backus-Naur The following syntax specification uses the Augmented Backus-Naur
Form (ABNF) notation as specified in [ABNF]. Form (ABNF) notation as specified in [ABNF].
Non-terminals referenced but not defined below are as defined by Non-terminals referenced but not defined below are as defined by
[IMAP4] or [IMAPABNF]. [IMAP4], [CONDSTORE] or [IMAPABNF].
Except as noted otherwise, all alphabetic characters are case- Except as noted otherwise, all alphabetic characters are case-
insensitive. The use of upper or lower case characters to define insensitive. The use of upper or lower case characters to define
token strings is for editorial clarity only. Implementations MUST token strings is for editorial clarity only. Implementations MUST
accept these strings in a case-insensitive fashion. accept these strings in a case-insensitive fashion.
capability =/ "X-DRAFT-I02-ESEARCH" capability =/ "X-DRAFT-I02-ESEARCH"
search-return-data = "MIN" SP nz-number / search-return-data = "MIN" SP nz-number /
"MAX" SP nz-number / "MAX" SP nz-number /
"ALL" SP sequence-set / "ALL" SP sequence-set /
"COUNT" SP number "COUNT" SP number
;; conforms to the generic ;; conforms to the generic
;; search-return-data syntax defined ;; search-return-data syntax defined
;; in [IMAPABNF] ;; in [IMAPABNF]
search-return-opt = "MIN" / "MAX" / "ALL" / "COUNT" search-return-opt = "MIN" / "MAX" / "ALL" / "COUNT"
;; conforms to generic search-return-opt ;; conforms to generic search-return-opt
;; syntax defined in [IMAPABNF] ;; syntax defined in [IMAPABNF]
<<extend MIN & MAX to allow for parameters?>> When the CONDSTORE [CONDSTORE] IMAP extension is also supported
the ABNF is updated as follows:
<<When the CONDSTORE IMAP extension is also supported <<add
reference>> the ABNF is updated as follows:
search-return-data =/ "MODSEQ" SP mod-sequence-value search-return-data =/ "MODSEQ" SP mod-sequence-value
>> ;; mod-sequence-value is defined
;; in [CONDSTORE]
5. Security Considerations 5. Security Considerations
<<TBD>> In general case IMAP SEARCH/UID SEARCH command can be CPU and/or IO
intensive, so some sites/implementations even disable it entirely.
This is quite unfortunate, as SEARCH command is one of the best
examples demonstrating IMAP advantage over 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 load on IMAP servers, which chose to optimize
SEARCHes containing only one or both of them.
It is believed that this extension doesn't raise any additional
security concerns not already discussed in [IMAP4].
6. IANA Considerations 6. IANA Considerations
IMAP4 capabilities are registered by publishing a standards track IMAP4 capabilities are registered by publishing a standards track
or IESG approved experimental RFC. The registry is currently or IESG approved experimental RFC. The registry is currently
located at located at
<http://www.iana.org/assignments/imap4-capabilities>. <http://www.iana.org/assignments/imap4-capabilities>.
This document defines the X-DRAFT-I02-ESEARCH <<fix before This document defines the X-DRAFT-I02-ESEARCH <<fix before
publication>> IMAP capability. IANA is requested to add this publication>> IMAP capability. IANA is requested to add this
capability to the registry. capability to the registry.
skipping to change at line 262 skipping to change at line 299
[KEYWORDS] Bradner, S., "Key words for use in RFCs to Indicate [KEYWORDS] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", RFC 2119, March 1997. Requirement Levels", RFC 2119, March 1997.
[IMAP4] Crispin, M., "Internet Message Access Protocol - Version [IMAP4] Crispin, M., "Internet Message Access Protocol - Version
4rev1", RFC 3501, University of Washington, March 2003. 4rev1", RFC 3501, University of Washington, March 2003.
[ABNF] Crocker, D. (Ed.) and P. Overell , "Augmented BNF for Syntax [ABNF] Crocker, D. (Ed.) and P. Overell , "Augmented BNF for Syntax
Specifications: ABNF", RFC 4234, October 2005. Specifications: ABNF", RFC 4234, October 2005.
[IMAPABNF] Melnikov, A., "Collected extensions to IMAP4 ABNF", work [IMAPABNF] Melnikov, A. and C. Daboo, "Collected extensions to
in progress, draft-melnikov-imap-ext-abnf-XX.txt. IMAP4 ABNF", RFC 4466, April 2006..
7.2 Informative References
[TRANS-CAPA] Melnikov, A., "Transitional IMAP capabilities", work [CONDSTORE] Melnikov, A. and S. Hole, "IMAP Extension for
in progress, draft-melnikov-imap-transitional-capa-XX.txt Conditional STORE", RFC 4551, June 2006.
<<This reference is to be deleted before publication.>>
8. Acknowledgments 8. Acknowledgments
Thanks to Michael Wener, Arnt Gulbrandsen, Cyrus Daboo, Mark Thanks to Michael Wener, Arnt Gulbrandsen, Cyrus Daboo, Mark
Crispin and Pete Maclean for comments and corrections. Crispin and Pete Maclean for comments and corrections.
9. Author's Addresses 9. Author's Addresses
Alexey Melnikov Alexey Melnikov
Isode Limited Isode Limited
skipping to change at line 295 skipping to change at line 329
Email: Alexey.Melnikov@isode.com Email: Alexey.Melnikov@isode.com
Dave A. Cridland Dave A. Cridland
Inventure Systems Limited Inventure Systems Limited
Email: dave.cridland@inventuresystems.co.uk Email: dave.cridland@inventuresystems.co.uk
URL: http://invsys.co.uk/dave/ URL: http://invsys.co.uk/dave/
10. Full Copyright Statement 10. Full Copyright Statement
Copyright (C) The Internet Society (2005). Copyright (C) The Internet Society (2006).
This document is subject to the rights, licenses and restrictions This document is subject to the rights, licenses and restrictions
contained in BCP 78, and except as set forth therein, the authors contained in BCP 78, and except as set forth therein, the authors
retain all their rights. retain all their rights.
This document and the information contained herein are provided on This document and the information contained herein are provided on
an "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE an "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE
REPRESENTS OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY AND REPRESENTS OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY AND
THE INTERNET ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, THE INTERNET ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES,
EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT
skipping to change at line 341 skipping to change at line 375
at http://www.ietf.org/ipr. at http://www.ietf.org/ipr.
The IETF invites any interested party to bring to its attention any The IETF invites any interested party to bring to its attention any
copyrights, patents or patent applications, or other proprietary copyrights, patents or patent applications, or other proprietary
rights that may cover technology that may be required to implement rights that may cover technology that may be required to implement
this standard. Please address the information to the IETF at ietf- this standard. Please address the information to the IETF at ietf-
ipr@ietf.org. ipr@ietf.org.
12. Appendix A. Editorial. 12. Appendix A. Editorial.
<<Note that this section will be deleted before publication>> <<Note to RFC editor: please delete this section before
publication>>
12.1 Change Log 12.1 Change Log
00 Initial Revision. 00 Initial Revision.
01 Added search correlator. Clarified what should be returned if an 01 Added search correlator. Clarified what should be returned if an
extended SEARCH produces no matches. Filled in "IANA considerations" extended SEARCH produces no matches. Filled in "IANA
section. Updated references: updated ABNF and added [IMAPABNF]. considerations" section. Updated references: updated ABNF and
Changed semantics of the empty list of result options (now equivalent added [IMAPABNF]. Changed semantics of the empty list of result
to "(ALL)". options (now equivalent to "(ALL)".
02 Clarified that clients can expect a single ESEARCH result to any 02 Clarified that clients can expect a single ESEARCH result to any
extended SEARCH command (for return options described in this extended SEARCH command (for result options described in this
document). Added more text on intended purpose of the extension. document). Added more text on intended purpose of the extension.
Added more examples. Updated reference to the ABNF document. Added more examples. Updated reference to the ABNF document.
03 Clarified interaction with CONDSTORE. Multiple editorial changes
12.2 Open Issues for Discussion to align with [IMAPABNF].
Should the syntax allow for return option parameters? It might be
convenient to specify "MIN (10)" and then "NEXT (15)" in order to
get SEARCH paged results.
 End of changes. 20 change blocks. 
63 lines changed or deleted 98 lines changed or added

This html diff was produced by rfcdiff 1.48. The latest version is available from http://tools.ietf.org/tools/rfcdiff/