1.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
     1.2 +++ b/docs/rfc/rfc4315.txt	Mon Sep 14 15:17:45 2009 +0900
     1.3 @@ -0,0 +1,451 @@
     1.4 +
     1.5 +
     1.6 +
     1.7 +
     1.8 +
     1.9 +
    1.10 +Network Working Group                                         M. Crispin
    1.11 +Request for Comments: 4315                                 December 2005
    1.12 +Obsoletes: 2359
    1.13 +Category: Standards Track
    1.14 +
    1.15 +
    1.16 +      Internet Message Access Protocol (IMAP) - UIDPLUS extension
    1.17 +
    1.18 +Status of This Memo
    1.19 +
    1.20 +   This document specifies an Internet standards track protocol for the
    1.21 +   Internet community, and requests discussion and suggestions for
    1.22 +   improvements.  Please refer to the current edition of the "Internet
    1.23 +   Official Protocol Standards" (STD 1) for the standardization state
    1.24 +   and status of this protocol.  Distribution of this memo is unlimited.
    1.25 +
    1.26 +Copyright Notice
    1.27 +
    1.28 +   Copyright (C) The Internet Society (2005).
    1.29 +
    1.30 +Abstract
    1.31 +
    1.32 +   The UIDPLUS extension of the Internet Message Access Protocol (IMAP)
    1.33 +   provides a set of features intended to reduce the amount of time and
    1.34 +   resources used by some client operations.  The features in UIDPLUS
    1.35 +   are primarily intended for disconnected-use clients.
    1.36 +
    1.37 +1.  Introduction and Overview
    1.38 +
    1.39 +   The UIDPLUS extension is present in any IMAP server implementation
    1.40 +   that returns "UIDPLUS" as one of the supported capabilities to the
    1.41 +   CAPABILITY command.
    1.42 +
    1.43 +   The UIDPLUS extension defines an additional command.  In addition,
    1.44 +   this document recommends new status response codes in IMAP that
    1.45 +   SHOULD be returned by all server implementations, regardless of
    1.46 +   whether or not the UIDPLUS extension is implemented.
    1.47 +
    1.48 +   The added facilities of the features in UIDPLUS are optimizations;
    1.49 +   clients can provide equivalent functionality, albeit less
    1.50 +   efficiently, by using facilities in the base protocol.
    1.51 +
    1.52 +1.1.  Conventions Used in This Document
    1.53 +
    1.54 +   In examples, "C:" and "S:" indicate lines sent by the client and
    1.55 +   server, respectively.
    1.56 +
    1.57 +
    1.58 +
    1.59 +
    1.60 +
    1.61 +Crispin                     Standards Track                     [Page 1]
    1.62 +
    1.63 +RFC 4315                IMAP - UIDPLUS Extension           December 2005
    1.64 +
    1.65 +
    1.66 +   The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
    1.67 +   "SHOULD", "SHOULD NOT", "MAY", and "OPTIONAL" in this document are to
    1.68 +   be interpreted as described in [KEYWORDS].
    1.69 +
    1.70 +   A "UID set" is similar to the [IMAP] sequence set; however, the "*"
    1.71 +   value for a sequence number is not permitted.
    1.72 +
    1.73 +2.  Additional Commands
    1.74 +
    1.75 +   The following command definition is an extension to [IMAP] section
    1.76 +   6.4.
    1.77 +
    1.78 +2.1.  UID EXPUNGE Command
    1.79 +
    1.80 +   Arguments:  sequence set
    1.81 +
    1.82 +   Data:       untagged responses: EXPUNGE
    1.83 +
    1.84 +   Result:     OK - expunge completed
    1.85 +               NO - expunge failure (e.g., permission denied)
    1.86 +               BAD - command unknown or arguments invalid
    1.87 +
    1.88 +      The UID EXPUNGE command permanently removes all messages that both
    1.89 +      have the \Deleted flag set and have a UID that is included in the
    1.90 +      specified sequence set from the currently selected mailbox.  If a
    1.91 +      message either does not have the \Deleted flag set or has a UID
    1.92 +      that is not included in the specified sequence set, it is not
    1.93 +      affected.
    1.94 +
    1.95 +      This command is particularly useful for disconnected use clients.
    1.96 +      By using UID EXPUNGE instead of EXPUNGE when resynchronizing with
    1.97 +      the server, the client can ensure that it does not inadvertantly
    1.98 +      remove any messages that have been marked as \Deleted by other
    1.99 +      clients between the time that the client was last connected and
   1.100 +      the time the client resynchronizes.
   1.101 +
   1.102 +      If the server does not support the UIDPLUS capability, the client
   1.103 +      should fall back to using the STORE command to temporarily remove
   1.104 +      the \Deleted flag from messages it does not want to remove, then
   1.105 +      issuing the EXPUNGE command.  Finally, the client should use the
   1.106 +      STORE command to restore the \Deleted flag on the messages in
   1.107 +      which it was temporarily removed.
   1.108 +
   1.109 +      Alternatively, the client may fall back to using just the EXPUNGE
   1.110 +      command, risking the unintended removal of some messages.
   1.111 +
   1.112 +
   1.113 +
   1.114 +
   1.115 +
   1.116 +
   1.117 +Crispin                     Standards Track                     [Page 2]
   1.118 +
   1.119 +RFC 4315                IMAP - UIDPLUS Extension           December 2005
   1.120 +
   1.121 +
   1.122 +   Example:    C: A003 UID EXPUNGE 3000:3002
   1.123 +               S: * 3 EXPUNGE
   1.124 +               S: * 3 EXPUNGE
   1.125 +               S: * 3 EXPUNGE
   1.126 +               S: A003 OK UID EXPUNGE completed
   1.127 +
   1.128 +3.  Additional Response Codes
   1.129 +
   1.130 +   The following response codes are extensions to the response codes
   1.131 +   defined in [IMAP] section 7.1.  With limited exceptions, discussed
   1.132 +   below, server implementations that advertise the UIDPLUS extension
   1.133 +   SHOULD return these response codes.
   1.134 +
   1.135 +   In the case of a mailbox that has permissions set so that the client
   1.136 +   can COPY or APPEND to the mailbox, but not SELECT or EXAMINE it, the
   1.137 +   server SHOULD NOT send an APPENDUID or COPYUID response code as it
   1.138 +   would disclose information about the mailbox.
   1.139 +
   1.140 +   In the case of a mailbox that has UIDNOTSTICKY status (as defined
   1.141 +   below), the server MAY omit the APPENDUID or COPYUID response code as
   1.142 +   it is not meaningful.
   1.143 +
   1.144 +   If the server does not return the APPENDUID or COPYUID response
   1.145 +   codes, the client can discover this information by selecting the
   1.146 +   destination mailbox.  The location of messages placed in the
   1.147 +   destination mailbox by COPY or APPEND can be determined by using
   1.148 +   FETCH and/or SEARCH commands (e.g., for Message-ID or some unique
   1.149 +   marker placed in the message in an APPEND).
   1.150 +
   1.151 +   APPENDUID
   1.152 +
   1.153 +      Followed by the UIDVALIDITY of the destination mailbox and the UID
   1.154 +      assigned to the appended message in the destination mailbox,
   1.155 +      indicates that the message has been appended to the destination
   1.156 +      mailbox with that UID.
   1.157 +
   1.158 +      If the server also supports the [MULTIAPPEND] extension, and if
   1.159 +      multiple messages were appended in the APPEND command, then the
   1.160 +      second value is a UID set containing the UIDs assigned to the
   1.161 +      appended messages, in the order they were transmitted in the
   1.162 +      APPEND command.  This UID set may not contain extraneous UIDs or
   1.163 +      the symbol "*".
   1.164 +
   1.165 +         Note: the UID set form of the APPENDUID response code MUST NOT
   1.166 +         be used if only a single message was appended.  In particular,
   1.167 +         a server MUST NOT send a range such as 123:123.  This is
   1.168 +         because a client that does not support [MULTIAPPEND] expects
   1.169 +         only a single UID and not a UID set.
   1.170 +
   1.171 +
   1.172 +
   1.173 +Crispin                     Standards Track                     [Page 3]
   1.174 +
   1.175 +RFC 4315                IMAP - UIDPLUS Extension           December 2005
   1.176 +
   1.177 +
   1.178 +      UIDs are assigned in strictly ascending order in the mailbox
   1.179 +      (refer to [IMAP], section 2.3.1.1) and UID ranges are as in
   1.180 +      [IMAP]; in particular, note that a range of 12:10 is exactly
   1.181 +      equivalent to 10:12 and refers to the sequence 10,11,12.
   1.182 +
   1.183 +      This response code is returned in a tagged OK response to the
   1.184 +      APPEND command.
   1.185 +
   1.186 +   COPYUID
   1.187 +
   1.188 +      Followed by the UIDVALIDITY of the destination mailbox, a UID set
   1.189 +      containing the UIDs of the message(s) in the source mailbox that
   1.190 +      were copied to the destination mailbox and containing the UIDs
   1.191 +      assigned to the copied message(s) in the destination mailbox,
   1.192 +      indicates that the message(s) have been copied to the destination
   1.193 +      mailbox with the stated UID(s).
   1.194 +
   1.195 +      The source UID set is in the order the message(s) were copied; the
   1.196 +      destination UID set corresponds to the source UID set and is in
   1.197 +      the same order.  Neither of the UID sets may contain extraneous
   1.198 +      UIDs or the symbol "*".
   1.199 +
   1.200 +      UIDs are assigned in strictly ascending order in the mailbox
   1.201 +      (refer to [IMAP], section 2.3.1.1) and UID ranges are as in
   1.202 +      [IMAP]; in particular, note that a range of 12:10 is exactly
   1.203 +      equivalent to 10:12 and refers to the sequence 10,11,12.
   1.204 +
   1.205 +      This response code is returned in a tagged OK response to the COPY
   1.206 +      command.
   1.207 +
   1.208 +   UIDNOTSTICKY
   1.209 +
   1.210 +      The selected mailbox is supported by a mail store that does not
   1.211 +      support persistent UIDs; that is, UIDVALIDITY will be different
   1.212 +      each time the mailbox is selected.  Consequently, APPEND or COPY
   1.213 +      to this mailbox will not return an APPENDUID or COPYUID response
   1.214 +      code.
   1.215 +
   1.216 +      This response code is returned in an untagged NO response to the
   1.217 +      SELECT command.
   1.218 +
   1.219 +         Note: servers SHOULD NOT have any UIDNOTSTICKY mail stores.
   1.220 +         This facility exists to support legacy mail stores in which it
   1.221 +         is technically infeasible to support persistent UIDs.  This
   1.222 +         should be avoided when designing new mail stores.
   1.223 +
   1.224 +
   1.225 +
   1.226 +
   1.227 +
   1.228 +
   1.229 +Crispin                     Standards Track                     [Page 4]
   1.230 +
   1.231 +RFC 4315                IMAP - UIDPLUS Extension           December 2005
   1.232 +
   1.233 +
   1.234 +   Example:    C: A003 APPEND saved-messages (\Seen) {297}
   1.235 +               C: Date: Mon, 7 Feb 1994 21:52:25 -0800 (PST)
   1.236 +               C: From: Fred Foobar <foobar@example.com>
   1.237 +               C: Subject: afternoon meeting
   1.238 +               C: To: mooch@example.com
   1.239 +               C: Message-Id: <B27397-0100000@example.com>
   1.240 +               C: MIME-Version: 1.0
   1.241 +               C: Content-Type: TEXT/PLAIN; CHARSET=US-ASCII
   1.242 +               C:
   1.243 +               C: Hello Joe, do you think we can meet at 3:30 tomorrow?
   1.244 +               C:
   1.245 +               S: A003 OK [APPENDUID 38505 3955] APPEND completed
   1.246 +               C: A004 COPY 2:4 meeting
   1.247 +               S: A004 OK [COPYUID 38505 304,319:320 3956:3958] Done
   1.248 +               C: A005 UID COPY 305:310 meeting
   1.249 +               S: A005 OK No matching messages, so nothing copied
   1.250 +               C: A006 COPY 2 funny
   1.251 +               S: A006 OK Done
   1.252 +               C: A007 SELECT funny
   1.253 +               S: * 1 EXISTS
   1.254 +               S: * 1 RECENT
   1.255 +               S: * OK [UNSEEN 1] Message 1 is first unseen
   1.256 +               S: * OK [UIDVALIDITY 3857529045] Validity session-only
   1.257 +               S: * OK [UIDNEXT 2] Predicted next UID
   1.258 +               S: * NO [UIDNOTSTICKY] Non-persistent UIDs
   1.259 +               S: * FLAGS (\Answered \Flagged \Deleted \Seen \Draft)
   1.260 +               S: * OK [PERMANENTFLAGS (\Deleted \Seen)] Limited
   1.261 +               S: A007 OK [READ-WRITE] SELECT completed
   1.262 +
   1.263 +   In this example, A003 and A004 demonstrate successful appending and
   1.264 +   copying to a mailbox that returns the UIDs assigned to the messages.
   1.265 +   A005 is an example in which no messages were copied; this is because
   1.266 +   in A003, we see that message 2 had UID 304, and message 3 had UID
   1.267 +   319; therefore, UIDs 305 through 310 do not exist (refer to section
   1.268 +   2.3.1.1 of [IMAP] for further explanation).  A006 is an example of a
   1.269 +   message being copied that did not return a COPYUID; and, as expected,
   1.270 +   A007 shows that the mail store containing that mailbox does not
   1.271 +   support persistent UIDs.
   1.272 +
   1.273 +4.  Formal Syntax
   1.274 +
   1.275 +   Formal syntax is defined using ABNF [ABNF], which extends the ABNF
   1.276 +   rules defined in [IMAP].  The IMAP4 ABNF should be imported before
   1.277 +   attempting to validate these rules.
   1.278 +
   1.279 +   append-uid      = uniqueid
   1.280 +
   1.281 +   capability      =/ "UIDPLUS"
   1.282 +
   1.283 +
   1.284 +
   1.285 +Crispin                     Standards Track                     [Page 5]
   1.286 +
   1.287 +RFC 4315                IMAP - UIDPLUS Extension           December 2005
   1.288 +
   1.289 +
   1.290 +   command-select  =/ uid-expunge
   1.291 +
   1.292 +   resp-code-apnd  = "APPENDUID" SP nz-number SP append-uid
   1.293 +
   1.294 +   resp-code-copy  = "COPYUID" SP nz-number SP uid-set SP uid-set
   1.295 +
   1.296 +   resp-text-code  =/ resp-code-apnd / resp-code-copy / "UIDNOTSTICKY"
   1.297 +                     ; incorporated before the expansion rule of
   1.298 +                     ;  atom [SP 1*<any TEXT-CHAR except "]">]
   1.299 +                     ; that appears in [IMAP]
   1.300 +
   1.301 +   uid-expunge     = "UID" SP "EXPUNGE" SP sequence-set
   1.302 +
   1.303 +   uid-set         = (uniqueid / uid-range) *("," uid-set)
   1.304 +
   1.305 +   uid-range       = (uniqueid ":" uniqueid)
   1.306 +                     ; two uniqueid values and all values
   1.307 +                     ; between these two regards of order.
   1.308 +                     ; Example: 2:4 and 4:2 are equivalent.
   1.309 +
   1.310 +   Servers that support [MULTIAPPEND] will have the following extension
   1.311 +   to the above rules:
   1.312 +
   1.313 +   append-uid      =/ uid-set
   1.314 +                     ; only permitted if client uses [MULTIAPPEND]
   1.315 +                     ; to append multiple messages.
   1.316 +
   1.317 +5.  Security Considerations
   1.318 +
   1.319 +   The COPYUID and APPENDUID response codes return information about the
   1.320 +   mailbox, which may be considered sensitive if the mailbox has
   1.321 +   permissions set that permit the client to COPY or APPEND to the
   1.322 +   mailbox, but not SELECT or EXAMINE it.
   1.323 +
   1.324 +   Consequently, these response codes SHOULD NOT be issued if the client
   1.325 +   does not have access to SELECT or EXAMINE the mailbox.
   1.326 +
   1.327 +6.  IANA Considerations
   1.328 +
   1.329 +   This document constitutes registration of the UIDPLUS capability in
   1.330 +   the imap4-capabilities registry, replacing [RFC2359].
   1.331 +
   1.332 +7.  Normative References
   1.333 +
   1.334 +   [ABNF]        Crocker, D. and P. Overell, "Augmented BNF for Syntax
   1.335 +                 Specifications: ABNF", RFC 4234, October 2005.
   1.336 +
   1.337 +
   1.338 +
   1.339 +
   1.340 +
   1.341 +Crispin                     Standards Track                     [Page 6]
   1.342 +
   1.343 +RFC 4315                IMAP - UIDPLUS Extension           December 2005
   1.344 +
   1.345 +
   1.346 +   [IMAP]        Crispin, M., "INTERNET MESSAGE ACCESS PROTOCOL -
   1.347 +                 VERSION 4rev1", RFC 3501, March 2003.
   1.348 +
   1.349 +   [KEYWORDS]    Bradner, S., "Key words for use in RFCs to Indicate
   1.350 +                 Requirement Levels", BCP 14, RFC 2119, March 1997.
   1.351 +
   1.352 +   [MULTIAPPEND] Crispin, M., "Internet Message Access Protocol (IMAP) -
   1.353 +                 MULTIAPPEND Extension", RFC 3502, March 2003.
   1.354 +
   1.355 +8.  Informative References
   1.356 +
   1.357 +   [RFC2359]     Myers, J., "IMAP4 UIDPLUS extension", RFC 2359, June
   1.358 +                 1998.
   1.359 +
   1.360 +9.  Changes from RFC 2359
   1.361 +
   1.362 +   This document obsoletes [RFC2359].  However, it is based upon that
   1.363 +   document, and takes substantial text from it (albeit with numerous
   1.364 +   clarifications in wording).
   1.365 +
   1.366 +   [RFC2359] implied that a server must always return COPYUID/APPENDUID
   1.367 +   data; thus suggesting that in such cases the server should return
   1.368 +   arbitrary data if the destination mailbox did not support persistent
   1.369 +   UIDs.  This document adds the UIDNOTSTICKY response code to indicate
   1.370 +   that a mailbox does not support persistent UIDs, and stipulates that
   1.371 +   a UIDPLUS server does not return COPYUID/APPENDUID data when the COPY
   1.372 +   (or APPEND) destination mailbox has UIDNOTSTICKY status.
   1.373 +
   1.374 +Author's Address
   1.375 +
   1.376 +   Mark R. Crispin
   1.377 +   Networks and Distributed Computing
   1.378 +   University of Washington
   1.379 +   4545 15th Avenue NE
   1.380 +   Seattle, WA  98105-4527
   1.381 +
   1.382 +   Phone: (206) 543-5762
   1.383 +   EMail: MRC@CAC.Washington.EDU
   1.384 +
   1.385 +
   1.386 +
   1.387 +
   1.388 +
   1.389 +
   1.390 +
   1.391 +
   1.392 +
   1.393 +
   1.394 +
   1.395 +
   1.396 +
   1.397 +Crispin                     Standards Track                     [Page 7]
   1.398 +
   1.399 +RFC 4315                IMAP - UIDPLUS Extension           December 2005
   1.400 +
   1.401 +
   1.402 +Full Copyright Statement
   1.403 +
   1.404 +   Copyright (C) The Internet Society (2005).
   1.405 +
   1.406 +   This document is subject to the rights, licenses and restrictions
   1.407 +   contained in BCP 78, and except as set forth therein, the authors
   1.408 +   retain all their rights.
   1.409 +
   1.410 +   This document and the information contained herein are provided on an
   1.411 +   "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS
   1.412 +   OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY AND THE INTERNET
   1.413 +   ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS OR IMPLIED,
   1.414 +   INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE
   1.415 +   INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED
   1.416 +   WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
   1.417 +
   1.418 +Intellectual Property
   1.419 +
   1.420 +   The IETF takes no position regarding the validity or scope of any
   1.421 +   Intellectual Property Rights or other rights that might be claimed to
   1.422 +   pertain to the implementation or use of the technology described in
   1.423 +   this document or the extent to which any license under such rights
   1.424 +   might or might not be available; nor does it represent that it has
   1.425 +   made any independent effort to identify any such rights.  Information
   1.426 +   on the procedures with respect to rights in RFC documents can be
   1.427 +   found in BCP 78 and BCP 79.
   1.428 +
   1.429 +   Copies of IPR disclosures made to the IETF Secretariat and any
   1.430 +   assurances of licenses to be made available, or the result of an
   1.431 +   attempt made to obtain a general license or permission for the use of
   1.432 +   such proprietary rights by implementers or users of this
   1.433 +   specification can be obtained from the IETF on-line IPR repository at
   1.434 +   http://www.ietf.org/ipr.
   1.435 +
   1.436 +   The IETF invites any interested party to bring to its attention any
   1.437 +   copyrights, patents or patent applications, or other proprietary
   1.438 +   rights that may cover technology that may be required to implement
   1.439 +   this standard.  Please address the information to the IETF at ietf-
   1.440 +   ipr@ietf.org.
   1.441 +
   1.442 +Acknowledgement
   1.443 +
   1.444 +   Funding for the RFC Editor function is currently provided by the
   1.445 +   Internet Society.
   1.446 +
   1.447 +
   1.448 +
   1.449 +
   1.450 +
   1.451 +
   1.452 +
   1.453 +Crispin                     Standards Track                     [Page 8]
   1.454 +