rfc4551.txt

广泛使用的邮件服务器！同时

Network Working Group                                        A. Melnikov
Request for Comments: 4551                                    Isode Ltd.
Updates: 3501                                                    S. Hole
Category: Standards Track                  ACI WorldWide/MessagingDirect
                                                               June 2006


             IMAP Extension for Conditional STORE Operation
                or Quick Flag Changes Resynchronization

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.

Copyright Notice

   Copyright (C) The Internet Society (2006).

Abstract

   Often, multiple IMAP (RFC 3501) clients need to coordinate changes to
   a common IMAP mailbox.  Examples include different clients working on
   behalf of the same user, and multiple users accessing shared
   mailboxes.  These clients need a mechanism to synchronize state
   changes for messages within the mailbox.  They must be able to
   guarantee that only one client can change message state (e.g.,
   message flags) at any time.  An example of such an application is use
   of an IMAP mailbox as a message queue with multiple dequeueing
   clients.

   The Conditional Store facility provides a protected update mechanism
   for message state information that can detect and resolve conflicts
   between multiple writing mail clients.

   The Conditional Store facility also allows a client to quickly
   resynchronize mailbox flag changes.

   This document defines an extension to IMAP (RFC 3501).









Melnikov & Hole             Standards Track                     [Page 1]

RFC 4551          IMAP Extension for Conditional STORE         June 2006


Table of Contents

   1.  Introduction and Overview ................................. 3
   2.  Conventions Used in This Document ......................... 5
   3.  IMAP Protocol Changes ..................................... 6
   3.1. New OK untagged responses for SELECT and EXAMINE ......... 6
   3.1.1. HIGHESTMODSEQ response code ............................ 6
   3.1.2. NOMODSEQ response code ................................. 7
   3.2. STORE and UID STORE Commands ............................. 7
   3.3 FETCH and UID FETCH Commands ..............................13
   3.3.1. CHANGEDSINCE FETCH modifier ............................13
   3.3.2. MODSEQ message data item in FETCH Command ..............14
   3.4. MODSEQ search criterion in SEARCH ........................16
   3.5. Modified SEARCH untagged response ........................17
   3.6. HIGHESTMODSEQ status data items ..........................17
   3.7. CONDSTORE parameter to SELECT and EXAMINE ................18
   3.8. Additional quality of implementation issues ..............18
   4.  Formal Syntax .............................................19
   5.  Server implementation considerations ......................21
   6.  Security Considerations ...................................22
   7.  IANA Considerations .......................................22
   8.  References ................................................23
   8.1. Normative References .....................................23
   8.2. Informative References ...................................23
   9.  Acknowledgements ..........................................23


























Melnikov & Hole             Standards Track                     [Page 2]

RFC 4551          IMAP Extension for Conditional STORE         June 2006


1. Introduction and Overview

   The Conditional STORE extension is present in any IMAP4
   implementation that returns "CONDSTORE" as one of the supported
   capabilities in the CAPABILITY command response.

   An IMAP server that supports this extension MUST associate a positive
   unsigned 64-bit value called a modification sequence (mod-sequence)
   with every IMAP message.  This is an opaque value updated by the
   server whenever a metadata item is modified.  The server MUST
   guarantee that each STORE command performed on the same mailbox
   (including simultaneous stores to different metadata items from
   different connections) will get a different mod-sequence value.
   Also, for any two successful STORE operations performed in the same
   session on the same mailbox, the mod-sequence of the second completed
   operation MUST be greater than the mod-sequence of the first
   completed.  Note that the latter rule disallows the use of the system
   clock as a mod-sequence, because if system time changes (e.g., an NTP
   [NTP] client adjusting the time), the next generated value might be
   less than the previous one.

   Mod-sequences allow a client that supports the CONDSTORE extension to
   determine if a message metadata has changed since some known moment.
   Whenever the state of a flag changes (i.e., the flag is added where
   previously it wasn't set, or the flag is removed and before it was
   set) the value of the modification sequence for the message MUST be
   updated.  Adding the flag when it is already present or removing when
   it is not present SHOULD NOT change the mod-sequence.

   When a message is appended to a mailbox (via the IMAP APPEND command,
   COPY to the mailbox, or using an external mechanism) the server
   generates a new modification sequence that is higher than the highest
   modification sequence of all messages in the mailbox and assigns it
   to the appended message.

   The server MAY store separate (per-message) modification sequence
   values for different metadata items.  If the server does so, per-
   message mod-sequence is the highest mod-sequence of all metadata
   items for the specified message.

   The server that supports this extension is not required to be able to
   store mod-sequences for every available mailbox.  Section 3.1.2
   describes how the server may act if a particular mailbox doesn't
   support the persistent storage of mod-sequences.







Melnikov & Hole             Standards Track                     [Page 3]

RFC 4551          IMAP Extension for Conditional STORE         June 2006


   This extension makes the following changes to the IMAP4 protocol:

      a) adds UNCHANGEDSINCE STORE modifier.

      b) adds the MODIFIED response code which should be used with an OK
         response to the STORE command.  (It can also be used in a NO
         response.)

      c) adds a new MODSEQ message data item for use with the FETCH
         command.

      d) adds CHANGEDSINCE FETCH modifier.

      e) adds a new MODSEQ search criterion.

      f) extends the syntax of untagged SEARCH responses to include
         mod-sequence.

      g) adds new OK untagged responses for the SELECT and EXAMINE
         commands.

      h) defines an additional parameter to SELECT/EXAMINE commands.

      i) adds the HIGHESTMODSEQ status data item to the STATUS command.

   A client supporting CONDSTORE extension indicates its willingness to
   receive mod-sequence updates in all untagged FETCH responses by
   issuing:

      -  a SELECT or EXAMINE command with the CONDSTORE parameter,
      -  a STATUS (HIGHESTMODSEQ) command,
      -  a FETCH or SEARCH command that includes the MODSEQ message data
         item,
      -  a FETCH command with the CHANGEDSINCE modifier, or
      -  a STORE command with the UNCHANGEDSINCE modifier.

   The server MUST include mod-sequence data in all subsequent untagged
   FETCH responses (until the connection is closed), whether they were
   caused by a regular STORE, a STORE with UNCHANGEDSINCE modifier, or
   an external agent.

   This document uses the term "CONDSTORE-aware client" to refer to a
   client that announces its willingness to receive mod-sequence updates
   as described above.  The term "CONDSTORE enabling command" will refer
   any of the commands listed above.  A future extension to this
   document may extend the list of CONDSTORE enabling commands.  A first
   CONDSTORE enabling command executed in the session MUST cause the




Melnikov & Hole             Standards Track                     [Page 4]

RFC 4551          IMAP Extension for Conditional STORE         June 2006


   server to return HIGHESTMODSEQ (Section 3.1.1) unless the server has
   sent NOMODSEQ (Section 3.1.2) response code when the currently
   selected mailbox was selected.

   The rest of this document describes the protocol changes more
   rigorously.

2.  Conventions Used in This Document

   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].

   In examples, lines beginning with "S:" are sent by the IMAP server,
   and lines beginning with "C:" are sent by the client.  Line breaks
   may appear in example commands solely for editorial clarity; when
   present in the actual message, they are represented by "CRLF".

   Formal syntax is defined using ABNF [ABNF].

   The term "metadata" or "metadata item" is used throughout this
   document.  It refers to any system or user-defined keyword.  Future
   documents may extend "metadata" to include other dynamic message
   data.

   Some IMAP mailboxes are private, accessible only to the owning user.
   Other mailboxes are not, either because the owner has set an Access
   Control List [ACL] that permits access by other users, or because it
   is a shared mailbox.  Let's call a metadata item "shared" for the
   mailbox if any changes to the metadata items are persistent and
   visible to all other users accessing the mailbox.  Otherwise, the
   metadata item is called "private".  Note that private metadata items
   are still visible to all sessions accessing the mailbox as the same
   user.  Also note that different mailboxes may have different metadata
   items as shared.

   See Section 1 for the definition of a "CONDSTORE-aware client" and a
   "CONDSTORE enabling command".













Melnikov & Hole             Standards Track                     [Page 5]

RFC 4551          IMAP Extension for Conditional STORE         June 2006


3.  IMAP Protocol Changes

3.1.  New OK Untagged Responses for SELECT and EXAMINE

   This document adds two new response codes, HIGHESTMODSEQ and
   NOMODSEQ.  One of those response codes MUST be returned in the OK
   untagged response for a successful SELECT/EXAMINE command.

   When opening a mailbox, the server must check if the mailbox supports
   the persistent storage of mod-sequences.  If the mailbox supports the
   persistent storage of mod-sequences and the mailbox open operation
   succeeds, the server MUST send the OK untagged response including
   HIGHESTMODSEQ response code.  If the persistent storage for the
   mailbox is not supported, the server MUST send the OK untagged
   response including NOMODSEQ response code instead.

3.1.1.  HIGHESTMODSEQ Response Code

   This document adds a new response code that is returned in the OK
   untagged response for the SELECT and EXAMINE commands.  A server
   supporting the persistent storage of mod-sequences for the mailbox
   MUST send the OK untagged response including HIGHESTMODSEQ response
   code with every successful SELECT or EXAMINE command:

      OK [HIGHESTMODSEQ <mod-sequence-value>]

      where <mod-sequence-value> is the highest mod-sequence value of
      all messages in the mailbox.  When the server changes UIDVALIDITY
      for a mailbox, it doesn't have to keep the same HIGHESTMODSEQ for
      the mailbox.

   A disconnected client can use the value of HIGHESTMODSEQ to check if
   it has to refetch metadata from the server.  If the UIDVALIDITY value
   has changed for the selected mailbox, the client MUST delete the
   cached value of HIGHESTMODSEQ.  If UIDVALIDITY for the mailbox is the
   same, and if the HIGHESTMODSEQ value stored in the client's cache is
   less than the value returned by the server, then some metadata items
   on the server have changed since the last synchronization, and the
   client needs to update its cache.  The client MAY use SEARCH MODSEQ
   (Section 3.4) to find out exactly which metadata items have changed.
   Alternatively, the client MAY issue FETCH with the CHANGEDSINCE
   modifier (Section 3.3.1) in order to fetch data for all messages that
   have metadata items changed since some known modification sequence.

   Example 1:

      C: A142 SELECT INBOX
      S: * 172 EXISTS



Melnikov & Hole             Standards Track                     [Page 6]

RFC 4551          IMAP Extension for Conditional STORE         June 2006


      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