doc/src/rfc2359.txt

   1
   2
   3
   4
   5
   6
   7 Network Working Group                                           J. Myers
   8 Request for Comments: 2359                       Netscape Communications
   9 Category: Standards Track                                      June 1998
  10
  11
  12                         IMAP4 UIDPLUS extension
  13
  14 Status of this Memo
  15
  16    This document specifies an Internet standards track protocol for the
  17    Internet community, and requests discussion and suggestions for
  18    improvements.  Please refer to the current edition of the "Internet
  19    Official Protocol Standards" (STD 1) for the standardization state
  20    and status of this protocol.  Distribution of this memo is unlimited.
  21
  22 Copyright Notice
  23
  24    Copyright (C) The Internet Society (1998).  All Rights Reserved.
  25
  26 IESG NOTE
  27
  28    The IMAP extension described here assumes a particular means of using
  29    IMAP to support disconnected operation.  However, this means of
  30    supporting disconnected operation is not yet documented.  Also, there
  31    are multiple theories about how best to do disconnected operation in
  32    IMAP, and as yet, there is no consensus on which one should be
  33    adopted as a standard.
  34
  35    This document is being approved as a Proposed Standard because it
  36    does not appear to have technical flaws in itelf.  However, approval
  37    of this document as a Proposed Standard should not be considered an
  38    IETF endorsement of any particular means of doing disconnected
  39    operation in IMAP.
  40
  41 Table of Contents
  42
  43    1.   Abstract ..............................................    2
  44    2.   Conventions Used in this Document .....................    2
  45    3.   Introduction and Overview .............................    2
  46    4.   Features ..............................................    2
  47    4.1. UID EXPUNGE Command ...................................    2
  48    4.2. APPENDUID response code ...............................    3
  49    4.3. COPYUID response code .................................    4
  50    5.   Formal Syntax .........................................    4
  51    6.   References ............................................    4
  52    7.   Security Considerations ...............................    5
  53    8.   Author's Address ......................................    5
  54    9.   Full Copyright Statement ..............................    6
  55
  56
  57
  58 Myers                       Standards Track                     [Page 1]
  59 \f
  60 RFC 2359                IMAP4 UIDPLUS extension                June 1998
  61
  62
  63 1.   Abstract
  64
  65    The UIDPLUS extension of the Internet Message Access Protocol [IMAP4]
  66    provides a set of features intended to reduce the amount of time and
  67    resources used by some client operations.  The features in UIDPLUS
  68    are primarily intended for disconnected-use clients.
  69
  70 2.   Conventions Used in this Document
  71
  72    In examples, "C:" and "S:" indicate lines sent by the client and
  73    server respectively.
  74
  75    The key words "MUST", "MUST NOT", "SHOULD", "SHOULD NOT", and "MAY"
  76    in this document are to be interpreted as defined in "Key words for
  77    use in RFCs to Indicate Requirement Levels" [KEYWORDS].
  78
  79 3.   Introduction and Overview
  80
  81    The UIDPLUS extension is present in any IMAP4 server implementation
  82    which returns "UIDPLUS" as one of the supported capabilities to the
  83    CAPABILITY command.  The UIDPLUS extension contains one additional
  84    command and additional data returned with successful APPEND and COPY
  85    commands.
  86
  87    Clients that wish to use the new command in UIDPLUS must of course
  88    first test for the presence of the extension by issuing a CAPABILITY
  89    command.  Each of the features in UIDPLUS are optimizations; clients
  90    can provide the same functionality, albeit more slowly, by using
  91    commands in the base protocol.  With each feature, this document
  92    recommends a fallback approach to take when the UIDPLUS extension is
  93    not supported by the server.
  94
  95 4.   Features
  96
  97 4.1. UID EXPUNGE Command
  98
  99    Arguments:  message set
 100
 101    Data:       untagged responses: EXPUNGE
 102
 103    Result:     OK - expunge completed
 104                NO - expunge failure (e.g. permission denied)
 105                BAD - command unknown or arguments invalid
 106
 107
 108
 109
 110
 111
 112
 113
 114 Myers                       Standards Track                     [Page 2]
 115 \f
 116 RFC 2359                IMAP4 UIDPLUS extension                June 1998
 117
 118
 119       The UID EXPUNGE command permanently removes from the currently
 120       selected mailbox all messages that both have the \Deleted flag set
 121       and have a UID that is included in the specified message set.  If
 122       a message either does not have the \Deleted flag set or is has a
 123       UID that is not included in the specified message set, it is not
 124       affected.
 125
 126       This command may be used to ensure that a replayed EXPUNGE command
 127       does not remove any messages that have been marked as \Deleted
 128       between the time that the user requested the expunge operation and
 129       the time the server processes the command.
 130
 131       If the server does not support the UIDPLUS capability, the client
 132       should fall back to using the STORE command to temporarily remove
 133       the \Deleted flag from messages it does not want to remove.  The
 134       client could alternatively fall back to using the EXPUNGE command,
 135       risking the unintended removal of some messages.
 136
 137    Example:    C: A003 UID EXPUNGE 3000:3002
 138                S: * 3 EXPUNGE
 139                S: * 3 EXPUNGE
 140                S: * 3 EXPUNGE
 141                S: A003 OK UID EXPUNGE completed
 142
 143 4.2. APPENDUID response code
 144
 145    Successful APPEND commands return an APPENDUID response code in the
 146    tagged OK response.  The APPENDUID response code contains as
 147    arguments the UIDVALIDITY of the destination mailbox and the UID
 148    assigned to the appended message.
 149
 150    If the server does not support the UIDPLUS capability, the client can
 151    only discover this information by selecting the destination mailbox
 152    and issuing FETCH commands.
 153
 154    Example:    C: A003 APPEND saved-messages (\Seen) {310}
 155                C: Date: Mon, 7 Feb 1994 21:52:25 -0800 (PST)
 156                C: From: Fred Foobar <foobar@Blurdybloop.COM>
 157                C: Subject: afternoon meeting
 158                C: To: mooch@owatagu.siam.edu
 159                C: Message-Id: <B27397-0100000@Blurdybloop.COM>
 160                C: MIME-Version: 1.0
 161                C: Content-Type: TEXT/PLAIN; CHARSET=US-ASCII
 162                C:
 163                C: Hello Joe, do you think we can meet at 3:30 tomorrow?
 164                C:
 165                S: A003 OK [APPENDUID 38505 3955] APPEND completed
 166
 167
 168
 169
 170 Myers                       Standards Track                     [Page 3]
 171 \f
 172 RFC 2359                IMAP4 UIDPLUS extension                June 1998
 173
 174
 175 4.3. COPYUID response code
 176
 177    Successful COPY and UID COPY commands return a COPYUID response code
 178    in the tagged OK response whenever at least one message was copied.
 179    The COPYUID response code contains as an argument the UIDVALIDITY of
 180    the appended-to mailbox, a message set containing the UIDs of the
 181    messages copied to the destination mailbox, in the order they were
 182    copied, and a message containing the UIDs assigned to the copied
 183    messages, in the order they were assigned.  Neither of the message
 184    sets may contain extraneous UIDs or the symbol '*'.
 185
 186    If the server does not support the UIDPLUS capability, the client can
 187    only discover this information by selecting the destination mailbox
 188    and issuing FETCH commands.
 189
 190    Example:    C: A003 COPY 2:4 MEETING
 191                S: A003 OK [COPYUID 38505 304,319:320 3956:3958] Done
 192                C: A003 UID COPY 305:310 MEETING
 193                S: A003 OK Done
 194
 195 5.   Formal Syntax
 196
 197    The following syntax specification uses the augmented Backus-Naur
 198    Form (BNF) notation as specified in [RFC-822] as modified by [IMAP4].
 199    Non-terminals referenced but not defined below are as defined by
 200    [IMAP4].
 201
 202    Except as noted otherwise, all alphabetic characters are case-
 203    insensitive.  The use of upper or lower case characters to define
 204    token strings is for editorial clarity only.  Implementations MUST
 205    accept these strings in a case-insensitive fashion.
 206
 207    resp_code_apnd  ::= "APPENDUID" SPACE nz_number SPACE uniqueid
 208
 209    resp_code_copy  ::= "COPYUID" SPACE nz_number SPACE set SPACE set
 210
 211    uid_expunge     ::= "UID" SPACE "EXPUNGE" SPACE set
 212
 213 6.   References
 214
 215    [IMAP4]    Crispin, M., "Internet Message Access Protocol -
 216               Version 4rev1", RFC 2060, December 1996.
 217
 218    [KEYWORDS] Bradner, S., "Key words for use in RFCs to Indicate
 219               Requirement Levels", BCP 14, RFC 2119, March 1997.
 220
 221    [RFC-822]  Crocker, D., "Standard for the Format of ARPA Internet
 222               Text Messages", STD 11, RFC 822, August 1982.
 223
 224
 225
 226 Myers                       Standards Track                     [Page 4]
 227 \f
 228 RFC 2359                IMAP4 UIDPLUS extension                June 1998
 229
 230
 231 7.   Security Considerations
 232
 233    There are no known security issues with this extension.
 234
 235 8.   Author's Address
 236
 237    John Gardiner Myers
 238    Netscape Communications
 239    501 East Middlefield Road
 240    Mail Stop MV-029
 241    Mountain View, CA  94043
 242
 243    EMail: jgmyers@netscape.com
 244
 245
 246
 247
 248
 249
 250
 251
 252
 253
 254
 255
 256
 257
 258
 259
 260
 261
 262
 263
 264
 265
 266
 267
 268
 269
 270
 271
 272
 273
 274
 275
 276
 277
 278
 279
 280
 281
 282 Myers                       Standards Track                     [Page 5]
 283 \f
 284 RFC 2359                IMAP4 UIDPLUS extension                June 1998
 285
 286
 287 9.  Full Copyright Statement
 288
 289    Copyright (C) The Internet Society (1998).  All Rights Reserved.
 290
 291    This document and translations of it may be copied and furnished to
 292    others, and derivative works that comment on or otherwise explain it
 293    or assist in its implementation may be prepared, copied, published
 294    and distributed, in whole or in part, without restriction of any
 295    kind, provided that the above copyright notice and this paragraph are
 296    included on all such copies and derivative works.  However, this
 297    document itself may not be modified in any way, such as by removing
 298    the copyright notice or references to the Internet Society or other
 299    Internet organizations, except as needed for the purpose of
 300    developing Internet standards in which case the procedures for
 301    copyrights defined in the Internet Standards process must be
 302    followed, or as required to translate it into languages other than
 303    English.
 304
 305    The limited permissions granted above are perpetual and will not be
 306    revoked by the Internet Society or its successors or assigns.
 307
 308    This document and the information contained herein is provided on an
 309    "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING
 310    TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING
 311    BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION
 312    HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF
 313    MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
 314
 315
 316
 317
 318
 319
 320
 321
 322
 323
 324
 325
 326
 327
 328
 329
 330
 331
 332
 333
 334
 335
 336
 337
 338 Myers                       Standards Track                     [Page 6]
 339 \f