the server must not fail the operation for message 7 as part of
processing "3:9" if it succeeded when message 7 was processed the
first time.
Once the client specified the UNCHANGEDSINCE modifier in a STORE
command, the server MUST include the MODSEQ fetch response data items
in all subsequent unsolicited FETCH responses.
This document also changes the behaviour of the server when it has
performed a STORE or UID STORE command and the UNCHANGEDSINCE
modifier is not specified. If the operation is successful for a
message, the server MUST update the mod-sequence attribute of the
message. The server is REQUIRED to include the mod-sequence value
whenever it decides to send the unsolicited FETCH response to all
CONDSTORE-aware clients that have opened the mailbox containing the
message.
Server implementers should also see Section 3.8 for additional
quality of implementation issues related to the STORE command.
3.3. FETCH and UID FETCH Commands
3.3.1. CHANGEDSINCE FETCH Modifier
This document defines the following FETCH modifier (see Section 2.4
of [IMAPABNF]):
CHANGEDSINCE <mod-sequence>
CHANGEDSINCE FETCH modifier allows to create a further subset of
the list of messages described by sequence set. The information
described by message data items is only returned for messages that
have mod-sequence bigger than <mod-sequence>.
When CHANGEDSINCE FETCH modifier is specified, it implicitly adds
MODSEQ FETCH message data item (Section 3.3.2).
Example 12:
C: s100 UID FETCH 1:* (FLAGS) (CHANGEDSINCE 12345)
S: * 1 FETCH (UID 4 MODSEQ (65402) FLAGS (\Seen))
S: * 2 FETCH (UID 6 MODSEQ (75403) FLAGS (\Deleted))
S: * 4 FETCH (UID 8 MODSEQ (29738) FLAGS ($NoJunk $AutoJunk
$MDNSent))
S: s100 OK FETCH completed
3.3.2. MODSEQ Message Data Item in FETCH Command
This extension adds a MODSEQ message data item to the FETCH command.
The MODSEQ message data item allows clients to retrieve mod-sequence
values for a range of messages in the currently selected mailbox.
Once the client specified the MODSEQ message data item in a FETCH
request, the server MUST include the MODSEQ fetch response data items
in all subsequent unsolicited FETCH responses.
Syntax: MODSEQ
The MODSEQ message data item causes the server to return MODSEQ
fetch response data items.
Syntax: MODSEQ ( <permsg-modsequence> )
MODSEQ response data items contain per-message mod-sequences.
The MODSEQ response data item is returned if the client issued
FETCH with MODSEQ message data item. It also allows the server to
notify the client about mod-sequence changes caused by conditional
STOREs (Section 3.2) and/or changes caused by external sources.
Example 13:
C: a FETCH 1:3 (MODSEQ)
S: * 1 FETCH (MODSEQ (624140003))
S: * 2 FETCH (MODSEQ (624140007))
S: * 3 FETCH (MODSEQ (624140005))
S: a OK Fetch complete
In this example, the client requests per-message mod-sequences for
a set of messages.
When a flag for a message is modified in a different session, the
server sends an unsolicited FETCH response containing the mod-
sequence for the message.
Example 14:
(Session 1, authenticated as a user "alex"). The user adds a
shared flag \Deleted:
C: A142 SELECT INBOX
...
S: * FLAGS (\Answered \Flagged \Deleted \Seen \Draft)
S: * OK [PERMANENTFLAGS (\Answered \Deleted \Seen \*)] Limited
...
C: A160 STORE 7 +FLAGS.SILENT (\Deleted)
S: * 7 FETCH (MODSEQ (2121231000))
S: A160 OK Store completed
(Session 2, also authenticated as the user "alex"). Any changes
to flags are always reported to all sessions authenticated as the
same user as in the session 1.
C: C180 NOOP
S: * 7 FETCH (FLAGS (\Deleted \Answered) MODSEQ (12121231000))
S: C180 OK Noop completed
(Session 3, authenticated as a user "andrew"). As \Deleted is a
shared flag, changes in session 1 are also reported in session 3:
C: D210 NOOP
S: * 7 FETCH (FLAGS (\Deleted \Answered) MODSEQ (12121231000))
S: D210 OK Noop completed
The user modifies a private flag \Seen in session 1...
C: A240 STORE 7 +FLAGS.SILENT (\Seen)
S: * 7 FETCH (MODSEQ (12121231777))
S: A240 OK Store completed
...which is only reported in session 2...
C: C270 NOOP
S: * 7 FETCH (FLAGS (\Deleted \Answered \Seen) MODSEQ
(12121231777))
S: C270 OK Noop completed
...but not in session 3.
C: D300 NOOP
S: D300 OK Noop completed
And finally, the user removes flags \Answered (shared) and \Seen
(private) in session 1.
C: A330 STORE 7 -FLAGS.SILENT (\Answered \Seen)
S: * 7 FETCH (MODSEQ (12121245160))
S: A330 OK Store completed
Both changes are reported in the session 2...
C: C360 NOOP
S: * 7 FETCH (FLAGS (\Deleted) MODSEQ (12121245160))
S: C360 OK Noop completed
...and only changes to shared flags are reported in session 3.
C: D390 NOOP
S: * 7 FETCH (FLAGS (\Deleted) MODSEQ (12121245160))
S: D390 OK Noop completed
Server implementers should also see Section 3.8 for additional
quality of implementation issues related to the FETCH command.
3.4. MODSEQ Search Criterion in SEARCH
The MODSEQ criterion for the SEARCH command allows a client to search
for the metadata items that were modified since a specified moment.
Syntax: MODSEQ [<entry-name> <entry-type-req>] <mod-sequence-valzer>
Messages that have modification values that are equal to or
greater than <mod-sequence-valzer>. This allows a client, for
example, to find out which messages contain metadata items that
have changed since the last time it updated its disconnected
cache. The client may also specify <entry-name> (name of metadata
item) and <entry-type-req> (type of metadata item) before
<mod-sequence-valzer>. <entry-type-req> can be one of "shared",
"priv" (private), or "all". The latter means that the server
should use the biggest value among "priv" and "shared" mod-
sequences for the metadata item. If the server doesn’t store
internally separate mod-sequences for different metadata items, it
MUST ignore <entry-name> and <entry-type-req>. Otherwise, the
server should use them to narrow down the search.
For a flag <flagname>, the corresponding <entry-name> has a form
"/flags/<flagname>" as defined in [IMAPABNF]. Note that the
leading "\" character that denotes a system flag has to be escaped
as per Section 4.3 of [IMAP4], as the <entry-name> uses syntax for
quoted strings.
If client specifies a MODSEQ criterion in a SEARCH command and the
server returns a non-empty SEARCH result, the server MUST also append
(to the end of the untagged SEARCH response) the highest mod-sequence
for all messages being returned. See also Section 3.5.
Example 15:
C: a SEARCH MODSEQ "/flags/\\draft" all 620162338
S: * SEARCH 2 5 6 7 11 12 18 19 20 23 (MODSEQ 917162500)
S: a OK Search complete
In the above example, the message numbers of any messages
containing the string "IMAP4" in the "value" attribute of the
"/comment" entry and having a mod-sequence equal to or greater
than 620162338 for the "\Draft" flag are returned in the search
results.
Example 16:
C: t SEARCH OR NOT MODSEQ 720162338 LARGER 50000
S: * SEARCH
S: t OK Search complete, nothing found
3.5. Modified SEARCH Untagged Response
Data: zero or more numbers
mod-sequence value (omitted if no match)
This document extends syntax of the untagged SEARCH response to
include the highest mod-sequence for all messages being returned.
If a client specifies a MODSEQ criterion in a SEARCH (or UID SEARCH)
command and the server returns a non-empty SEARCH result, the server
MUST also append (to the end of the untagged SEARCH response) the
highest mod-sequence for all messages being returned. See Section
3.4 for examples.
3.6. HIGHESTMODSEQ Status Data Items
This document defines a new status data item:
HIGHESTMODSEQ
The highest mod-sequence value of all messages in the mailbox.
This is the same value that is returned by the server in the
HIGHESTMODSEQ response code in an OK untagged response (see
Section 3.1.1). If the server doesn’t support the persistent
storage of mod-sequences for the mailbox (see Section 3.1.2), the
server MUST return 0 as the value of HIGHESTMODSEQ status data
item.
Example 17:
C: A042 STATUS blurdybloop (UIDNEXT MESSAGES HIGHESTMODSEQ)
S: * STATUS blurdybloop (MESSAGES 231 UIDNEXT 44292
HIGHESTMODSEQ 7011231777)
S: A042 OK STATUS completed
3.7. CONDSTORE Parameter to SELECT and EXAMINE
The CONDSTORE extension defines a single optional select parameter,
"CONDSTORE", which tells the server that it MUST include the MODSEQ
fetch response data items in all subsequent unsolicited FETCH
responses.
The CONDSTORE parameter to SELECT/EXAMINE helps avoid a race
condition that might arise when one or more metadata items are
modified in another session after the server has sent the
HIGHESTMODSEQ response code and before the client was able to issue a
CONDSTORE enabling command.
Example 18:
C: A142 SELECT INBOX (CONDSTORE)
S: * 172 EXISTS
S: * 1 RECENT
S: * OK [UNSEEN 12] Message 12 is first unseen
S: * OK [UIDVALIDITY 3857529045] UIDs valid
S: * OK [UIDNEXT 4392] Predicted next UID
S: * FLAGS (\Answered \Flagged \Deleted \Seen \Draft)
S: * OK [PERMANENTFLAGS (\Deleted \Seen \*)] Limited
S: * OK [HIGHESTMODSEQ 715194045007]
S: A142 OK [READ-WRITE] SELECT completed, CONDSTORE is now enabled
3.8. Additional Quality-of-Implementation Issues
Server implementations should follow the following rule, which
applies to any successfully completed STORE/UID STORE (with and
without UNCHANGEDSINCE modifier), as well as to a FETCH command that
implicitly sets \Seen flag:
Adding the flag when it is already present or removing when it is
not present SHOULD NOT change the mod-sequence.
This will prevent spurious client synchronization requests.
However, note that client implementers MUST NOT rely on this server
behavior. A client can’t distinguish between the case when a server
has violated the SHOULD mentioned above, and that when one or more
clients set and unset (or unset and set) the flag in another session.
4. Formal Syntax
The following syntax specification uses the Augmented Backus-Naur
Form (ABNF) [ABNF] notation. Elements not defined here can be found
in the formal syntax of the ABNF [ABNF], IMAP [IMAP4], and IMAP ABNF
extensions [IMAPABNF] specifications.
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 =/ "CONDSTORE"
status-att =/ "HIGHESTMODSEQ"
;; extends non-terminal defined in RFC 3501.
status-att-val =/ "HIGHESTMODSEQ" SP mod-sequence-valzer
;; extends non-terminal defined in [IMAPABNF].
;; Value 0 denotes that the mailbox doesn’t
;; support persistent mod-sequences
;; as described in Section 3.1.2
store-modifier =/ "UNCHANGEDSINCE" SP mod-sequence-valzer
;; Only a single "UNCHANGEDSINCE" may be
;; specified in a STORE operation
fetch-modifier =/ chgsince-fetch-mod
;; conforms to the generic "fetch-modifier"
;; syntax defined in [IMAPABNF].
chgsince-fetch-mod = "CHANGEDSINCE" SP mod-sequence-value
;; CHANGEDSINCE FETCH modifier conforms to
;; the fetch-modifier syntax
fetch-att =/ fetch-mod-sequence
;; modifies original IMAP4 fetch-att
fetch-mod-sequence = "MODSEQ"
fetch-mod-resp = "MODSEQ" SP "(" permsg-modsequence ")"
msg-att-dynamic =/ fetch-mod-resp
search-key =/ search-modsequence
;; modifies original IMAP4 search-key
;;
;; This change applies to all commands
;; referencing this non-terminal, in
;; particular SEARCH.
search-modsequence = "MODSEQ" [search-modseq-ext] SP
mod-sequence-valzer
search-modseq-ext = SP entry-name SP entry-type-req
resp-text-code =/ "HIGHESTMODSEQ" SP mod-sequence-value /
"NOMODSEQ" /
"MODIFIED" SP set
entry-name = entry-flag-name
entry-flag-name = DQUOTE "/flags/" attr-flag DQUOTE
;; each system or user defined flag <flag>
;; is mapped to "/flags/<flag>".
;;
;; <entry-flag-name> follows the escape rules
;; used by "quoted" string as described in
;; Section 4.3 of [IMAP4], e.g., for the flag
;; \Seen the corresponding <entry-name> is
;; "/flags/\\seen", and for the flag
;; $MDNSent, the corresponding <entry-name>
;; is "/flags/$mdnsent".
entry-type-resp = "priv" / "shared"
;; metadata item type
entry-type-req = entry-type-resp / "all"
;; perform SEARCH operation on private
;; metadata item, shared metadata item or both
permsg-modsequence = mod-sequence-value
;; per message mod-sequence
mod-sequence-value = 1*DIGIT
;; Positive unsigned 64-bit integer
;; (mod-sequence)
;; (1 <= n < 18,446,744,073,709,551,615)
mod-sequence-valzer = "0" / mod-sequence-value
search-sort-mod-seq = "(" "MODSEQ" SP mod-sequence-value ")"
select-param =/ condstore-param
;; conforms to the generic "select-param"
;; non-terminal syntax defined in [IMAPABNF].
condstore-param = "CONDSTORE"
mailbox-data =/ "SEARCH" [1*(SP nz-number) SP
search-sort-mod-seq]
attr-flag = "\\Answered" / "\\Flagged" / "\\Deleted" /
"\\Seen" / "\\Draft" / attr-flag-keyword /
attr-flag-extension
;; Does not include "\\Recent"
attr-flag-extension = "\\" atom
;; Future expansion. Client implementations
;; MUST accept flag-extension flags. Server
;; implementations MUST NOT generate
;; flag-extension flags except as defined by
;; future standard or standards-track
;; revisions of [IMAP4].
attr-flag-keyword = atom
5. Server Implementation Considerations
This section describes how a server implementation that doesn’t store
separate per-metadata mod-sequences for different metadata items can
avoid sending the MODIFIED response to any of the following
conditional STORE operations:
+FLAGS
-FLAGS
+FLAGS.SILENT
-FLAGS.SILENT
Note that the optimization described in this section can’t be
performed in case of a conditional STORE FLAGS operation.
Let’s use the following example. The client has issued
C: a106 STORE 100:150 (UNCHANGEDSINCE 212030000000)
+FLAGS.SILENT ($Processed)
When the server receives the command and parses it successfully, it
iterates through the message set and tries to execute the conditional
STORE command for each message.
Each server internally works as a client, i.e., it has to cache the
current state of all IMAP flags as it is known to the client. In
order to report flag changes to the client, the server compares the
cached values with the values in its database for IMAP flags.
Imagine that another client has changed the state of a flag \Deleted
on the message 101 and that the change updated the mod-sequence for
the message. The server knows that the mod-sequence for the mailbox
has changed; however, it also knows that:
a) the client is not interested in \Deleted flag, as it hasn’t
included it in +FLAGS.SILENT operation; and
b) the state of the flag $Processed hasn’t changed (the server can
determine this by comparing cached flag state with the state of
the flag in the database).
Therefore, the server doesn’t have to report MODIFIED to the client.
Instead, the server may set $Processed flag, update the mod-sequence
for the message 101 once again and send an untagged FETCH response
with new mod-sequence and flags:
S: * 101 FETCH (MODSEQ (303011130956)
FLAGS ($Processed \Deleted \Answered))
See also Section 3.8 for additional quality-of-implementation issues.
6. Security Considerations
It is believed that the Conditional STORE extension doesn’t raise any
new security concerns that are not already discussed in [IMAP4].
However, the availability of this extension may make it possible for
IMAP4 to be used in critical applications it could not be used for
previously, making correct IMAP server implementation and operation
even more important.
7. IANA Considerations
IMAP4 capabilities are registered by publishing a standards track or
IESG approved experimental RFC. The registry is currently located
at:
http://www.iana.org/assignments/imap4-capabilities
This document defines the CONDSTORE IMAP capability. IANA has added
it to the registry accordingly.
8. References
8.1. Normative References
[KEYWORDS] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119, March 1997.
[ABNF] Crocker, D. and P. Overell, "Augmented BNF for Syntax
Specifications: ABNF", RFC 4234, October 2005.
[IMAP4] Crispin, M., "INTERNET MESSAGE ACCESS PROTOCOL - VERSION
4rev1", RFC 3501, March 2003.
[IMAPABNF] Melnikov, A. and C. Daboo, "Collected Extensions to IMAP4
ABNF", RFC 4466, April 2006.
8.2. Informative References
[ACAP] Newman, C. and J. Myers, "ACAP -- Application
Configuration Access Protocol", RFC 2244, November 1997.
[ACL] Melnikov, A., "IMAP4 Access Control List (ACL) Extension",
RFC 4314, December 2005.
[ANN] Daboo, C. and R. Gellens, "IMAP ANNOTATE Extension", Work
in Progress, March 2006.
[NTP] Mills, D., "Network Time Protocol (Version 3)
Specification, Implementation and Analysis", RFC 1305,
March 1992.
[RFC-2180] Gahrns, M., "IMAP4 Multi-Accessed Mailbox Practice", RFC
2180, July 1997.
9. Acknowledgements
Some text was borrowed from "IMAP ANNOTATE Extension" [ANN] by
Randall Gellens and Cyrus Daboo and from "ACAP -- Application
Configuration Access Protocol" [ACAP] by Chris Newman and John Myers.
Many thanks to Randall Gellens for his thorough review of the
document.
The authors also acknowledge the feedback provided by Cyrus Daboo,
Larry Greenfield, Chris Newman, Harrie Hazewinkel, Arnt Gulbrandsen,
Timo Sirainen, Mark Crispin, Ned Freed, Ken Murchison, and Dave
Cridland.
Authors’ Addresses
Alexey Melnikov
Isode Limited
5 Castle Business Village
36 Station Road
Hampton, Middlesex
TW12 2BX,
United Kingdom
EMail: Alexey.Melnikov@isode.com
Steve Hole
ACI WorldWide/MessagingDirect
#1807, 10088 102 Ave
Edmonton, AB
T5J 2Z1
Canada
EMail: Steve.Hole@messagingdirect.com
Full Copyright Statement
Copyright (C) The Internet Society (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.
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 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.
Intellectual Property