idnits 2.17.1 draft-daboo-imap-annotatemore-08.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- ** It looks like you're using RFC 3978 boilerplate. You should update this to the boilerplate described in the IETF Trust License Policy document (see https://trustee.ietf.org/license-info), which is required now. -- Found old boilerplate from RFC 3978, Section 5.1 on line 14. -- Found old boilerplate from RFC 3978, Section 5.5 on line 1196. -- Found old boilerplate from RFC 3979, Section 5, paragraph 1 on line 1173. -- Found old boilerplate from RFC 3979, Section 5, paragraph 2 on line 1180. -- Found old boilerplate from RFC 3979, Section 5, paragraph 3 on line 1186. ** This document has an original RFC 3978 Section 5.4 Copyright Line, instead of the newer IETF Trust Copyright according to RFC 4748. ** This document has an original RFC 3978 Section 5.5 Disclaimer, instead of the newer disclaimer which includes the IETF Trust according to RFC 4748. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- == No 'Intended status' indicated for this document; assuming Proposed Standard Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the RFC 3978 Section 5.4 Copyright Line does not match the current year -- The document seems to lack a disclaimer for pre-RFC5378 work, but may have content which was first submitted before 10 November 2008. If you have contacted all the original authors and they are all willing to grant the BCP78 rights to the IETF Trust, then this is fine, and you can ignore this comment. If not, you may need to add the pre-RFC5378 disclaimer. (See the Legal Provisions document at https://trustee.ietf.org/license-info for more information.) -- The document date (November 21, 2005) is 6723 days in the past. Is this intentional? -- Found something which looks like a code comment -- if you have code sections in the document, please surround them with '' and '' lines. Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) == Missing Reference: 'ANNOTATEMORE TOOMANY' is mentioned on line 621, but not defined == Outdated reference: A later version (-20) exists of draft-ietf-imapext-sort-17 == Outdated reference: A later version (-08) exists of draft-melnikov-imap-ext-abnf-05 ** Obsolete normative reference: RFC 2234 (Obsoleted by RFC 4234) ** Obsolete normative reference: RFC 3501 (Obsoleted by RFC 9051) == Outdated reference: A later version (-16) exists of draft-ietf-imapext-annotate-13 Summary: 5 errors (**), 0 flaws (~~), 6 warnings (==), 8 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group C. Daboo 3 Internet-Draft November 21, 2005 4 Expires: May 25, 2006 6 IMAP ANNOTATEMORE Extension 7 draft-daboo-imap-annotatemore-08 9 Status of this Memo 11 By submitting this Internet-Draft, each author represents that any 12 applicable patent or other IPR claims of which he or she is aware 13 have been or will be disclosed, and any of which he or she becomes 14 aware will be disclosed, in accordance with Section 6 of BCP 79. 16 Internet-Drafts are working documents of the Internet Engineering 17 Task Force (IETF), its areas, and its working groups. Note that 18 other groups may also distribute working documents as Internet- 19 Drafts. 21 Internet-Drafts are draft documents valid for a maximum of six months 22 and may be updated, replaced, or obsoleted by other documents at any 23 time. It is inappropriate to use Internet-Drafts as reference 24 material or to cite them other than as "work in progress." 26 The list of current Internet-Drafts can be accessed at 27 http://www.ietf.org/ietf/1id-abstracts.txt. 29 The list of Internet-Draft Shadow Directories can be accessed at 30 http://www.ietf.org/shadow.html. 32 This Internet-Draft will expire on May 25, 2006. 34 Copyright Notice 36 Copyright (C) The Internet Society (2005). 38 Abstract 40 The ANNOTATEMORE extension to the Internet Message Access Protocol 41 permits clients and servers to maintain annotations ("metadata") on 42 IMAP servers. It is possible to have annotations on a per-mailbox 43 basis or on the server as a whole. 45 Change History (to be removed prior to publication as an RFC) 47 Changes from -07 to -08: 49 1. Changed 'string' formal syntax to 'list-mailbox' and 'astring' 50 for entry/attribute names. 51 2. Updated examples to match new astring syntax. 52 3. Changed CAPABILITY name due to incompatible syntax change. 53 4. Removed content-type attribute. 54 5. Added Content-type to IANA registration for entries. 55 6. Removed vendor attributes. 56 7. Fixed examples in section 3.3 for multi-mailbox and multi-entry 57 cases. 58 8. Removed wildcards for attributes. 59 9. Entry/attributes can now only be ASCII. 60 10. Tied up text wrt storing/fetching. 61 11. Added Conventions section 62 12. Entry/attributes MUST NOT contain consecutive or trailing '/' or 63 '.'. 64 13. Changed to use IMAP ABNF extensions document for some formal 65 syntax items. 67 Changes from -06 to -07: 68 1. Reworded /checkperiod item. 69 2. Clarified unsolicited response behaviour. 71 Changes from -05 to -06: 72 1. Removed 'modifiedsince' attribute as there is currently no use 73 for it. 74 2. Added content-language attribute. 75 3. Changed access to allow .priv and .shared on any mailbox returned 76 by LIST/LSUB. 77 4. Added IANA registrations for items defined in this document. 78 5. Added latest IPR statement. 79 6. Updated references. 81 Changes from -04 to -05: 82 1. Fix for valid IMAP state of commands. 83 2. Fix formatting, ID nits etc. 85 Changes from -03 to -04: 86 1. Allow retrieval of shared annotations for READ-ONLY mailbox. 87 2. Clarification of annotation loss on implicit removal of \Noselect 88 mailboxes. 89 3. Now requires roll-back of all changes to matching mailboxes if 90 there is a partial failure in SETANNOTATION. 92 Changes from -02 to -03: 93 1. Reworked entry naming scheme to split out mailbox name and use 94 empty string for server items. 96 Changes from -01 to -02: 98 1. SETANNOTATION lists use (..). 99 2. Explicitly state behaviour of unsolicited responses. 100 3. Adding SHOULD behaviour for rename/delete of mailboxes. 101 4. Added statement about supporting annotations on \Noselect 102 mailboxes. 103 5. Cleaned up formal syntax to use IMAP string type for entry and 104 attributes, with requirements on how the string is formatted. 105 6. Use of ACAP vendor subtree registry for vendor tokens. 107 Changes from -00 to -01: 108 1. Multiple entry-att responses are now simply delimited by spaces 109 in line with ANNOTATE spec. Adjusted examples to match. 110 2. Fixed entry-list formal syntax item to account for unsolicited 111 parenthesised list of entries. 112 3. Removed setentries formal syntax item for simplicity since its 113 only used once. 114 4. Removed reference to 'message annotation' in section 5.1. 115 5. Changed formal syntax to restrict top level entries to /server 116 and /mailbox/{...} only. Re-arranged entry names section to 117 account for this change. 118 6. Added comment and example for ANNOTATION response to allow 119 servers to return separate responses for each entry if desired. 121 Table of Contents 123 1. Introduction and Overview . . . . . . . . . . . . . . . . . . 5 124 2. Conventions Used in This Document . . . . . . . . . . . . . . 5 125 3. Data Model . . . . . . . . . . . . . . . . . . . . . . . . . . 5 126 3.1. Overview . . . . . . . . . . . . . . . . . . . . . . . . . 5 127 3.2. Namespace of entries and attributes . . . . . . . . . . . 6 128 3.2.1. Entry Names . . . . . . . . . . . . . . . . . . . . . 7 129 3.2.2. Attribute Names . . . . . . . . . . . . . . . . . . . 8 130 3.3. Private versus Shared and Access Control . . . . . . . . . 9 131 4. IMAP Protocol Changes . . . . . . . . . . . . . . . . . . . . 9 132 4.1. General Considerations . . . . . . . . . . . . . . . . . . 9 133 4.2. GETANNOTATION Command . . . . . . . . . . . . . . . . . . 10 134 4.3. SETANNOTATION Command . . . . . . . . . . . . . . . . . . 12 135 4.4. ANNOTATION Response . . . . . . . . . . . . . . . . . . . 14 136 4.4.1. ANNOTATION response with attributes and values . . . . 15 137 4.4.2. Unsolicited ANNOTATION response without attributes 138 and values . . . . . . . . . . . . . . . . . . . . . . 16 139 5. Formal Syntax . . . . . . . . . . . . . . . . . . . . . . . . 17 140 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 18 141 6.1. Entry and Attribute Registration Template . . . . . . . . 19 142 6.2. Server Entry Registrations . . . . . . . . . . . . . . . . 19 143 6.2.1. /comment . . . . . . . . . . . . . . . . . . . . . . . 20 144 6.2.2. /motd . . . . . . . . . . . . . . . . . . . . . . . . 20 145 6.2.3. /admin . . . . . . . . . . . . . . . . . . . . . . . . 21 146 6.3. Mailbox Entry Registrations . . . . . . . . . . . . . . . 21 147 6.3.1. /comment . . . . . . . . . . . . . . . . . . . . . . . 21 148 6.3.2. /sort . . . . . . . . . . . . . . . . . . . . . . . . 22 149 6.3.3. /thread . . . . . . . . . . . . . . . . . . . . . . . 22 150 6.3.4. /check . . . . . . . . . . . . . . . . . . . . . . . . 23 151 6.3.5. /checkperiod . . . . . . . . . . . . . . . . . . . . . 23 152 6.4. Attribute Registrations . . . . . . . . . . . . . . . . . 23 153 6.4.1. value . . . . . . . . . . . . . . . . . . . . . . . . 24 154 6.4.2. size . . . . . . . . . . . . . . . . . . . . . . . . . 24 155 6.4.3. content-language . . . . . . . . . . . . . . . . . . . 25 156 7. Security Considerations . . . . . . . . . . . . . . . . . . . 25 157 8. References . . . . . . . . . . . . . . . . . . . . . . . . . . 25 158 8.1. Normative References . . . . . . . . . . . . . . . . . . . 25 159 8.2. Informative References . . . . . . . . . . . . . . . . . . 26 160 Appendix A. Acknowledgments . . . . . . . . . . . . . . . . . . . 26 161 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 27 162 Intellectual Property and Copyright Statements . . . . . . . . . . 28 164 1. Introduction and Overview 166 The ANNOTATEMORE extension is present in any IMAP [RFC3501] 167 implementation which returns "ANNOTATEMORE2" as one of the supported 168 capabilities in the CAPABILITY command response. 170 The goal of ANNOTATEMORE is to provide a means for clients to set and 171 retrieve "metadata" on an IMAP server. The metadata can be 172 associated with specific mailboxes or the server as a whole. 174 The ANNOTATEMORE extension adds two new commands and one new untagged 175 response to the IMAP base protocol. 177 This extension makes the following changes to the IMAP protocol: 179 adds a new SETANNOTATION command 180 adds a new GETANNOTATION command 181 adds a new ANNOTATION untagged response 182 adds a new ANNOTATEMORE response code 184 The data model used in ANNOTATEMORE is exactly the same as that used 185 in the ANNOTATE [I-D.ietf-imapext-annotate] extension to IMAP. This 186 is modeled after that of the Application Configuration Access 187 Protocol [RFC2244] with the exception of inheritance which is not 188 deemed necessary here. 190 The rest of this document describes the data model and protocol 191 changes more rigorously. 193 2. Conventions Used in This Document 195 In examples, "C:" and "S:" indicate lines sent by the client and 196 server respectively. 198 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 199 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 200 document are to be interpreted as described in [RFC2119]. 202 3. Data Model 204 3.1. Overview 206 The data model used in ANNOTATEMORE is one of a uniquely named entry 207 with a set of uniquely named attributes, each of which has a value. 208 Annotations can be added to mailboxes when a mailbox name is provided 209 as the first argument to the new commands, or to the server as a 210 whole when the empty string is provided as the first argument to the 211 new commands. 213 An annotation can contain multiple named entries. For example, a 214 general comment being added to a mailbox may have an entry name of 215 "/comment". This entry could include named attributes such as 216 "value", "size", "content-language" etc to represent properties and 217 data associated with the entry. 219 The protocol changes to IMAP described below allow a client to access 220 or change the values of any attributes in any entries in an 221 annotation, assuming it has sufficient access rights to do so. 223 3.2. Namespace of entries and attributes 225 Each annotation is made up of a set of entries. Each entry has a 226 hierarchical name, with each component of the name separated by a 227 slash ("/"). An entry name MUST NOT contain two consecutive "/" 228 characters and MUST NOT end with a "/" character. 230 Each entry is made up of a set of attributes. Each attribute has a 231 hierarchical name, with each component of the name separated by a 232 period ("."). An attribute name MUST NOT contain two consecutive "." 233 characters and MUST NOT end with a "." character. 235 The value of an attribute is NIL (has no value), or a string of zero 236 or more octets. 238 Entry and attribute names MUST NOT contain asterisk ("*") or percent 239 ("%") characters and MUST NOT contain non-ASCII characters or the 240 NULL octet. Invalid entry or attribute names result in a BAD 241 response in any IMAP commands where they are used. 243 Attribute names MUST NOT contain any hierarchical components with the 244 names "priv" or "shared" as those have special meaning (see 245 Section 3.3). 247 Entry and attribute names are case-sensitive. 249 Use of control or punctuation characters in entry and attribute names 250 is strongly discouraged. 252 This specification defines an initial set of entry and attribute 253 names available for use with mailbox and server annotations. In 254 addition an extension mechanism is described to allow additional 255 names to be added for extensibility. 257 3.2.1. Entry Names 259 Entry names MUST be specified in a standards track or IESG approved 260 experimental RFC, or fall under the vendor namespace. See 261 Section 6.1 for the registration template. 263 3.2.1.1. Server Entries 265 These entries are used when the mailbox name argument to the new 266 commands is the empty string. 268 /comment 269 Defines a comment or note associated with the server. 271 /motd 272 Defines a "message of the day" for the server. This entry is 273 always read-only - clients cannot change it. 275 /admin 276 Indicates a method for contacting the server administrator. This 277 may be a URI (e.g. a mailto URL) or other contact information, 278 such as a telephone number. This entry is always read-only - 279 clients cannot change it. 281 /vendor/ 282 Defines the top-level of entries associated with the server as 283 created by a particular product of some vendor. This entry can be 284 used by vendors to provide server or client specific annotations. 285 The vendor-token MUST be registered with IANA, using the ACAP 286 [RFC2244] vendor subtree registry. 288 3.2.1.2. Mailbox Entries 290 These entries are used when the mailbox name argument to the new 291 commands is not the empty string. 293 /comment 294 Defines a comment or note associated with a mailbox. 296 /sort 297 Defines the default sort criteria [I-D.ietf-imapext-sort] to use 298 when first displaying the mailbox contents to the user, or NIL if 299 sorting is not required. 301 /thread 302 Defines the default thread criteria [I-D.ietf-imapext-sort] to use 303 when first displaying the mailbox contents to the user, or NIL if 304 threading is not required. If both sort and thread are not NIL, 305 then threading should take precedence over sorting. 307 /check 308 Boolean value "true" or "false" that indicates whether this 309 mailbox should be checked at regular intervals by the client. The 310 interval in minutes is specified by the /checkperiod entry. 312 /checkperiod 313 Numeric value indicating a period of minutes that the client uses 314 to determine the interval of regular 'new mail' checks for the 315 corresponding mailbox. 317 /vendor/ 318 Defines the top-level of entries associated with a specific 319 mailbox as created by a particular product of some vendor. This 320 entry can be used by vendors to provide client specific 321 annotations. The vendor-token MUST be registered with IANA, using 322 the ACAP [RFC2244] vendor subtree registry. 324 3.2.2. Attribute Names 326 Attribute names MUST be specified in a standards track or IESG 327 approved experimental RFC. See Section 6.1 for the registration 328 template. 330 All attribute names implicitly have a ".priv" and a ".shared" suffix 331 which maps to private and shared versions of the entry. Retrieving 332 an annotation without using either suffix includes both. The client 333 MUST specify either a ".priv" or ".shared" suffix when setting an 334 annotation. 336 value 337 A string or binary data representing the value of the annotation. 338 To delete an annotation, the client can store "NIL" into the 339 value. The content represented by the string is determined by the 340 Content-type used to register the entry (see Section 6.1 for entry 341 registration templates). Where applicable, the registered 342 content-type MUST include a charset parameter. Text values SHOULD 343 use the utf-8 [RFC3629] character set. 344 Note that binary data (data which may contain the NULL octet) is 345 allowed (e.g. for storing images etc), and this extension uses the 346 "literal8" syntax element [I-D.melnikov-imap-ext-abnf] to allow 347 such data to be written to or read from the server. 349 size 350 The size of the value, in octets. Set automatically by the 351 server, read-only to clients. 353 content-language 354 Indicates the language used for the value. This follows the 355 format described in [RFC3282]. Clients SHOULD specify this 356 attribute when setting an annotation that uses text that can be 357 presented to the user. It is not required for enumerated or 358 numeric values such as flags etc. If a value is being set, 359 clients MUST ensure that it accurately reflects the content stored 360 in the value attribute. 361 Servers MUST ensure that the "content-language" attribute value is 362 kept in synchronization with the "value" attribute. To ensure 363 that, the server MUST remove any "content-language" attribute 364 value when the client changes a "value" attribute without also 365 including a matching "content-language" attribute in the same 366 SETANNOTATION command. 368 3.3. Private versus Shared and Access Control 370 As discussed in the ANNOTATE [I-D.ietf-imapext-annotate] extension 371 there is a need to support both private and shared annotations. This 372 document adopts the scheme used in [I-D.ietf-imapext-annotate] that 373 adds two standard suffixes for all attributes: ".shared" and ".priv". 374 A GETANNOTATION command which specifies neither uses both. 375 SETANNOTATION commands MUST explicitly use .priv or .shared suffixes. 377 A user can only set and retrieve private or shared annotations on a 378 mailbox which is returned to them via a LIST or LSUB command. If the 379 client attempts to set or retrieve annotations on other mailboxes, 380 the server MUST respond with a NO response. 382 4. IMAP Protocol Changes 384 4.1. General Considerations 386 The new commands and response each have a mailbox name argument, 387 indicating that the annotations being referred to are attached to the 388 specified mailbox. An empty string can be used for the mailbox name 389 to signify server annotations. 391 Both "*" and "%" list wildcard characters MAY be used in the mailbox 392 name argument to commands to match all possible occurrences of a 393 mailbox name pattern. However, "*" or "%" by themselves MUST NOT 394 match the empty string (server) entries. Server entries can only be 395 accessed by explicitly using the empty string as the mailbox name. 397 Servers SHOULD ensure that mailbox annotations are automatically 398 moved when the mailbox they refer to is renamed, i.e. the annotations 399 follow the mailbox. Servers SHOULD delete annotations for a mailbox 400 when the mailbox is deleted, so that a mailbox created with the same 401 name as a previously existing mailbox does not inherit the old 402 mailbox annotations. Servers SHOULD allow annotations on all 'types' 403 of mailbox, including ones reporting \Noselect for their LIST 404 response. Servers can implicitly remove \Noselect mailboxes when all 405 child mailboxes are removed, and as such any annotations associated 406 with the \Noselect mailbox SHOULD be removed. 408 The server is allowed to impose limitations on the size of any one 409 annotation or the total number of annotations for a single mailbox or 410 for the server as a whole. However, the server MUST accept a minimum 411 annotation data size of at least 1024 bytes, and a minimum annotation 412 count per server or mailbox of at least 10. 414 4.2. GETANNOTATION Command 416 This extension adds the GETANNOTATION command. This allows clients 417 to retrieve annotations. 419 This command is only available in authenticated or selected state 420 [RFC3501]. 422 Arguments: mailbox-name 423 entry-specifier 424 attribute-specifier 426 Responses: required ANNOTATION response 428 Result: OK - command completed 429 NO - command failure: can't access annotations on 430 that mailbox 431 BAD - command unknown or arguments invalid 433 The mailbox-name argument MUST be a valid mailbox name or the empty 434 string. In the later case, the annotations being referred to are the 435 ones for the server as a whole. 437 Example: 439 C: a GETANNOTATION "" /comment value.priv 440 S: * ANNOTATION "" /comment (value.priv "My comment") 441 S: a OK GETANNOTATION complete 443 In the above example, the contents of the "value" attribute for 444 the "/comment" server entry is requested by the client and 445 returned by the server. 447 "*" and "%" wildcard characters can be used in the entry specifier to 448 match one or more characters at that position, with the exception 449 that "%" does not match the "/" hierarchy delimiter. Thus an entry 450 specifier of "/%" would match entries such as "/comment" and 451 "/version", but not "/comment/note". 453 Example: 455 C: a GETANNOTATION "" /* value.priv 456 S: * ANNOTATION "" /comment (value.priv "My comment") 457 /version (value.priv "1.1") 458 /motd/today (value.priv "Closed at 1 pm") 459 S: a OK GETANNOTATION complete 461 In the above example, the contents of the "value" attributes for 462 any server entries are requested by the client and returned by the 463 server. 465 Example: 467 C: a GETANNOTATION "" /% value 468 S: * ANNOTATION /comment (value.priv "My comment") 469 (value.shared "Your comment") 470 /motd (value.priv "Its sunny outside!" 471 (value.shared "Today is a Holiday") 472 S: a OK GETANNOTATION complete 474 In the above example, the contents of the "value" attributes for 475 server entries at the top level of the entry hierarchy only, are 476 requested by the client and returned by the server. Both the 477 .priv and .shared values are returned, as neither were explicitly 478 requested. 480 Entry and attribute specifiers can be lists of atomic specifiers, so 481 that multiple items of each type may be returned in a single 482 GETANNOTATION command. 484 Example: 486 C: a GETANNOTATION "" (/comment /motd) value.priv 487 S: * ANNOTATION "" /comment (value.priv "My comment") 488 /motd (value.priv "Its sunny outside!") 489 S: a OK GETANNOTATION complete 491 In the above example, the contents of the "value" attributes for 492 the two server entries "/comment" and "/motd" are requested by the 493 client and returned by the server. 495 Example: 497 C: a GETANNOTATION "" /comment (value.priv 498 content-language.priv) 499 S: * ANNOTATION "" /comment (value.priv "My comment" 500 content-language.priv "en_GB") 501 S: a OK GETANNOTATION complete 503 In the above example, the contents of the "value" and "content- 504 language" attributes for the "/comment" server entry are requested 505 by the client and returned by the server. 507 4.3. SETANNOTATION Command 509 This extension adds the SETANNOTATION command. This allows clients 510 to set annotations. 512 This command is only available in authenticated or selected state 513 [RFC3501]. 515 Arguments: mailbox-name 516 entry 517 attribute-value 518 list of entry, attribute-values 520 Responses: no specific responses for this command 522 Result: OK - command completed 523 NO - command failure: can't set annotations, 524 or annotation too big or too many 525 BAD - command unknown or arguments invalid 527 Sets the specified list of entries by adding or replacing the 528 specified attributes with the values provided. Clients can use NIL 529 for values of attributes it wants to remove from entries. The server 530 MAY return an ANNOTATION response containing the updated annotation 531 data. Clients MUST NOT assume that an ANNOTATION response will be 532 sent, and MUST assume that if the command succeeds then the 533 annotation has been changed. 535 If the server is unable to set an annotation because the size of its 536 value is too large, the server MUST return a tagged NO response with 537 a "[ANNOTATEMORE TOOBIG]" response code. 539 If the server is unable to set a new annotation because the maximum 540 number of allowed annotations has already been reached, the server 541 MUST return a tagged NO response with a "[ANNOTATEMORE TOOMANY]" 542 response code. 544 If the server is unable to set the annotations for one or more 545 mailboxes matching the mailbox-name pattern, then the SETANNOTATION 546 command MUST fail and there MUST NOT be any changes to any of the 547 matching mailboxes, even those for which annotations could have been 548 changed successfully. 550 Example: 552 C: a SETANNOTATION INBOX /comment 553 (value.priv "My new comment") 554 S: a OK SETANNOTATION complete 556 In the above example, the entry "/comment" for the mailbox "INBOX" 557 is created (if not already present) and the private attribute 558 "value" with data set to "My new comment" is created if not 559 already present, or replaced if it previously exists. 561 Example: 563 C: a SETANNOTATION INBOX /comment (value.priv NIL) 564 S: a OK SETANNOTATION complete 566 In the above example, the private "value" attribute of the entry 567 "/comment" is removed from the mailbox "INBOX". 569 Annotations on multiple mailboxes can be set in a single 570 SETANNOTATION command by using a wildcard specification for the 571 mailbox name. 573 Example: 575 C: a SETANNOTATION INBOX.% /comment 576 (value.priv "My new comment") 577 S: a OK SETANNOTATION complete 579 In the above example, the entry "/comment" for all mailboxes at 580 the top-level of the "INBOX" hierarchy are created (if not already 581 present) and the private attribute "value" are created 582 respectively for each entry if not already present, or replaced if 583 they previously existed. 585 Multiple entries can be set in a single SETANNOTATION command by 586 listing entry-attribute-value pairs in the list. 588 Example: 590 C: a SETANNOTATION INBOX (/comment 591 (value.priv "My new comment") 592 /thread 593 (value.prov "REFERENCES ALL")) 594 S: a OK SETANNOTATION complete 596 In the above example, the entry "/comment" for all mailboxes at 597 the top-level of the "INBOX" hierarchy are created (if not already 598 present) and the private and shared attributes "value" are created 599 respectively for each entry if not already present, or replaced if 600 they previously existed. 602 Multiple attributes can be set in a single SETANNOTATION command by 603 listing multiple attribute-value pairs in the entry list. 605 Example: 607 C: a SETANNOTATION INBOX /comment 608 (value.priv "My new comment" 609 value.shared "foo's bar") 610 S: a OK SETANNOTATION complete 612 In the above example, the entry "/comment" for the mailbox "INBOX" 613 is created (if not already present) and the attributes 614 "value.priv" and "value.shared" are created if not already 615 present, or replaced if they previously existed. 617 Example: 619 C: a SETANNOTATION INBOX /comment 620 (value.priv "My new comment") 621 S: a NO [ANNOTATEMORE TOOMANY] SETANNOTATION failed 623 In the above example, the server is unable to set the requested 624 (new) annotation as it has reached the limit on the number of 625 annotations it can support on the specified mailbox. 627 4.4. ANNOTATION Response 629 The ANNOTATION response displays results of a GETANNOTATION command, 630 or can be returned as an unsolicited response at anytime by the 631 server in response to a change in an annotation. 633 Servers SHOULD send unsolicited ANNOTATION responses if mailbox or 634 server annotations are changed by a third-party, allowing servers to 635 keep clients updated with changes. Unsolicited mailbox annotations 636 MUST only be returned for the currently selected mailbox. 638 Unsolicited ANNOTATION responses MUST only contain entry names, not 639 the attributes and values. If the client wants to update any cached 640 values it must explicitly retrieve those using a GETANNOTATION 641 command. 643 Separate ANNOTATION responses MUST be used when more than one mailbox 644 matches the mailbox name argument pattern to the command. 646 The ANNOTATION response can contain multiple entries in a single 647 response, but the server is free to return multiple responses for 648 each entry or group of entries if it desires. 650 This response is only available in authenticated state [RFC3501]. 652 4.4.1. ANNOTATION response with attributes and values 654 The response consists of a list of entries each of which has a list 655 of attribute-value pairs. 657 Example: 659 C: a GETANNOTATION "" /comment value.priv 660 S: * ANNOTATION "" /comment (value.priv "My comment") 661 S: a OK GETANNOTATION complete 663 In the above example, a single entry with a single attribute-value 664 pair is returned by the server. 666 Example: 668 C: a GETANNOTATION "" (/comment /motd) value.priv 669 S: * ANNOTATION "" /comment (value.priv "My comment") 670 /motd (value.priv "Its sunny outside!") 671 S: a OK GETANNOTATION complete 673 In the above example, two entries each with a single attribute- 674 value pair is returned by the server. 676 Example: 678 C: a GETANNOTATION "" (/comment /motd) value.priv 679 S: * ANNOTATION "" /comment (value.priv "My comment") 680 S: * ANNOTATION "" /motd (value.priv "Its sunny outside!") 681 S: a OK GETANNOTATION complete 683 In the above example, the server returns two separate responses 684 for each of the two entries requested. 686 Example: 688 C: a GETANNOTATION "" /comment (value.priv size.priv) 689 S: * ANNOTATION "" /comment (value.priv "My comment" 690 size.priv "10") 691 S: a OK GETANNOTATION complete 693 In the above example, a single entry with two attribute-value 694 pairs is returned by the server. 696 Example: 698 C: a GETANNOTATION INBOX.% /comment value.priv 699 S: * ANNOTATION INBOX.1 /comment 700 (value.priv "My comment for 1") 701 S: * ANNOTATION INBOX.2 /comment 702 (value.priv "My comment for 2") 703 S: * ANNOTATION INBOX.3 /comment 704 (value.priv "My comment for 3") 705 S: a OK GETANNOTATION complete 707 In the above example, separate responses are returned for each 708 matching mailbox, each containing a single entry with a single 709 attribute-value pair. 711 4.4.2. Unsolicited ANNOTATION response without attributes and values 713 The response consists of a parenthesised list of entries, each of 714 which have changed on the server. 716 Example: 718 C: a NOOP 719 S: * ANNOTATION "" (/comment) 720 S: a OK NOOP complete 722 In the above example, the server indicates that the "/comment" 723 server entry has been changed. 725 Example: 727 C: a NOOP 728 S: * ANNOTATION "" (/comment /motd) 729 S: a OK NOOP complete 731 In the above example, the server indicates a change to two server 732 entries. 734 Example: 736 C: a NOOP 737 S: * ANNOTATION "" (/motd) 738 S: * ANNOTATION INBOX (/comment) 739 S: a OK NOOP complete 741 In the above example, the server indicates a change to a server 742 entry, and to the an entry for the currently selected mailbox. 744 5. Formal Syntax 746 The following syntax specification uses the Augmented Backus-Naur 747 Form (ABNF) notation as specified in [RFC2234]. 749 Non-terminals referenced but not defined below are as defined by 750 [RFC3501] with the new definitions in [I-D.melnikov-imap-ext-abnf] 751 superseding those in [RFC3501]. 753 Except as noted otherwise, all alphabetic characters are case- 754 insensitive. The use of upper or lower case characters to define 755 token strings is for editorial clarity only. Implementations MUST 756 accept these strings in a case-insensitive fashion. 758 annotate-data = "ANNOTATION" SP mailbox SP entry-list 759 ; empty string for mailbox implies 760 ; server annotation. 762 att-value = attrib SP value 764 attrib = astring 765 ; dot-separated attribute name 766 ; MUST NOT contain "*" or "%" 768 attribs = attrib / "(" attrib *(SP attrib) ")" 769 ; one or more attribute specifiers 771 capability =/ "ANNOTATEMORE2" 772 ; defines the capability for this extension 774 command-auth =/ setannotation / getannotation 775 ; adds to original IMAP command 777 entries = entry-match / 778 "(" entry-match *(SP entry-match) ")" 779 ; entry specifiers that can include wildcards 781 entry = astring 782 ; slash-separated path to entry 783 ; MUST NOT contain "*" or "%" 785 entry-att = entry SP "(" att-value *(SP att-value) ")" 787 entry-list = entry-att *(SP entry-att) / 788 "(" entry *(SP entry) ")" 789 ; entry attribute-value pairs list for 790 ; GETANNOTATION response, or 791 ; parenthesised entry list for unsolicited 792 ; notification of annotation changes 794 entry-match = list-mailbox 795 ; slash-separated path to entry 796 ; MAY contain "*" or "%" for use as wildcards 798 getannotation = "GETANNOTATION" SP list-mailbox 799 SP entries SP attribs 800 ; empty string for list-mailbox implies 801 ; server annotation. 803 response-payload =/ annotate-data 804 ; adds to original IMAP data responses 806 resp-text-code =/ "ANNOTATEMORE" SP "TOOBIG" / 807 "ANNOTATEMORE" SP "TOOMANY" 808 ; new response codes for SETANNOTATION 809 ; failures 811 setannotation = "SETANNOTATION" SP list-mailbox 812 SP setentryatt 813 ; empty string for list-mailbox implies 814 ; server annotation. 816 setentryatt = entry-att / "(" entry-att *(SP entry-att) ")" 818 value = nstring / literal8 820 6. IANA Considerations 822 Entry names MUST be specified in a standards track or IESG approved 823 experimental RFC, or fall under the vendor namespace. Attribute 824 names MUST be specified in a standards track or IESG approved 825 experimental RFC. 827 Each entry registration MUST include a content-type that is used to 828 indicate the nature of the annotation value. Where applicable a 829 charset parameter MUST be included with the content-type. 831 6.1. Entry and Attribute Registration Template 833 To: iana@iana.org 834 Subject: IMAP ANNOTATEMORE Registration 836 Please register the following IMAP ANNOTATEMORE item: 838 [ ] Entry [ ] Attribute 840 [ ] Mailbox [ ] Server 842 Name: ______________________________ 844 Description: _______________________ 846 ____________________________________ 848 ____________________________________ 850 Content-type: ____________________ 852 Contact person: ____________________ 854 email: ____________________ 856 6.2. Server Entry Registrations 858 The following templates specify the IANA registrations of annotation 859 entries specified in this document. 861 6.2.1. /comment 863 To: iana@iana.org 864 Subject: IMAP ANNOTATEMORE Registration 866 Please register the following IMAP ANNOTATEMORE item: 868 [x] Entry [ ] Attribute 870 [ ] Mailbox [x] Server 872 Name: /comment 874 Description: Defined in IMAP ANNOTATEMORE extension document. 876 Content-type: text/plain; charset=utf-8 878 Contact person: Cyrus Daboo 880 email: cyrus@daboo.name 882 6.2.2. /motd 884 To: iana@iana.org 885 Subject: IMAP ANNOTATEMORE Registration 887 Please register the following IMAP ANNOTATEMORE item: 889 [x] Entry [ ] Attribute 891 [ ] Mailbox [x] Server 893 Name: /motd 895 Description: Defined in IMAP ANNOTATEMORE extension document. 897 Content-type: text/plain; charset=utf-8 899 Contact person: Cyrus Daboo 901 email: cyrus@daboo.name 903 6.2.3. /admin 905 To: iana@iana.org 906 Subject: IMAP ANNOTATEMORE Registration 908 Please register the following IMAP ANNOTATEMORE item: 910 [x] Entry [ ] Attribute 912 [ ] Mailbox [x] Server 914 Name: /admin 916 Description: Defined in IMAP ANNOTATEMORE extension document. 918 Content-type: text/plain; charset=utf-8 920 Contact person: Cyrus Daboo 922 email: cyrus@daboo.name 924 6.3. Mailbox Entry Registrations 926 The following templates specify the IANA registrations of annotation 927 entries specified in this document. 929 6.3.1. /comment 931 To: iana@iana.org 932 Subject: IMAP ANNOTATEMORE Registration 934 Please register the following IMAP ANNOTATEMORE item: 936 [x] Entry [ ] Attribute 938 [x] Mailbox [ ] Server 940 Name: /comment 942 Description: Defined in IMAP ANNOTATEMORE extension document. 944 Content-type: text/plain; charset=utf-8 946 Contact person: Cyrus Daboo 948 email: cyrus@daboo.name 950 6.3.2. /sort 952 To: iana@iana.org 953 Subject: IMAP ANNOTATEMORE Registration 955 Please register the following IMAP ANNOTATEMORE item: 957 [x] Entry [ ] Attribute 959 [x] Mailbox [ ] Server 961 Name: /sort 963 Description: Defined in IMAP ANNOTATEMORE extension document. 965 Content-type: text/plain; charset=utf-8 967 Contact person: Cyrus Daboo 969 email: cyrus@daboo.name 971 6.3.3. /thread 973 To: iana@iana.org 974 Subject: IMAP ANNOTATEMORE Registration 976 Please register the following IMAP ANNOTATEMORE item: 978 [x] Entry [ ] Attribute 980 [x] Mailbox [ ] Server 982 Name: /thread 984 Description: Defined in IMAP ANNOTATEMORE extension document. 986 Content-type: text/plain; charset=utf-8 988 Contact person: Cyrus Daboo 990 email: cyrus@daboo.name 992 6.3.4. /check 994 To: iana@iana.org 995 Subject: IMAP ANNOTATEMORE Registration 997 Please register the following IMAP ANNOTATEMORE item: 999 [x] Entry [ ] Attribute 1001 [x] Mailbox [ ] Server 1003 Name: /check 1005 Description: Defined in IMAP ANNOTATEMORE extension document. 1007 Content-type: text/plain; charset=utf-8 1009 Contact person: Cyrus Daboo 1011 email: cyrus@daboo.name 1013 6.3.5. /checkperiod 1015 To: iana@iana.org 1016 Subject: IMAP ANNOTATEMORE Registration 1018 Please register the following IMAP ANNOTATEMORE item: 1020 [x] Entry [ ] Attribute 1022 [x] Mailbox [ ] Server 1024 Name: /checkperiod 1026 Description: Defined in IMAP ANNOTATEMORE extension document. 1028 Content-type: text/plain; charset=utf-8 1030 Contact person: Cyrus Daboo 1032 email: cyrus@daboo.name 1034 6.4. Attribute Registrations 1036 The following templates specify the IANA registrations of annotation 1037 attributes specified in this document. 1039 6.4.1. value 1041 To: iana@iana.org 1042 Subject: IMAP ANNOTATEMORE Registration 1044 Please register the following IMAP ANNOTATEMORE item: 1046 [ ] Entry [x] Attribute 1048 [ ] Mailbox [ ] Server 1050 Name: value 1052 Description: Defined in IMAP ANNOTATEMORE extension document. 1054 Content-type: - 1056 Contact person: Cyrus Daboo 1058 email: cyrus@daboo.name 1060 6.4.2. size 1062 To: iana@iana.org 1063 Subject: IMAP ANNOTATEMORE Registration 1065 Please register the following IMAP ANNOTATEMORE item: 1067 [ ] Entry [x] Attribute 1069 [ ] Mailbox [ ] Server 1071 Name: size 1073 Description: Defined in IMAP ANNOTATEMORE extension document. 1075 Content-type: - 1077 Contact person: Cyrus Daboo 1079 email: cyrus@daboo.name 1081 6.4.3. content-language 1083 To: iana@iana.org 1084 Subject: IMAP ANNOTATEMORE Registration 1086 Please register the following IMAP ANNOTATEMORE item: 1088 [ ] Entry [x] Attribute 1090 [ ] Mailbox [ ] Server 1092 Name: content-language 1094 Description: Defined in IMAP ANNOTATEMORE extension document. 1096 Content-type: - 1098 Contact person: Cyrus Daboo 1100 email: cyrus@daboo.name 1102 7. Security Considerations 1104 Annotations whose values are intended to remain private MUST use 1105 .priv values, and not .shared values which may be accessible to other 1106 users. 1108 >Excluding the above issues the ANNOTATEMORE extension does not raise 1109 any security considerations that are not present in the base IMAP 1110 protocol, and these issues are discussed in [RFC3501]. 1112 8. References 1114 8.1. Normative References 1116 [I-D.ietf-imapext-sort] 1117 Crispin, M. and K. Murchison, "INTERNET MESSAGE ACCESS 1118 PROTOCOL - SORT AND THREAD EXTENSION", 1119 draft-ietf-imapext-sort-17 (work in progress), May 2004. 1121 [I-D.melnikov-imap-ext-abnf] 1122 Daboo, C. and A. Melnikov, "Collected extensions to IMAP4 1123 ABNF", draft-melnikov-imap-ext-abnf-05 (work in progress), 1124 October 2005. 1126 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1127 Requirement Levels", BCP 14, RFC 2119, March 1997. 1129 [RFC2234] Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax 1130 Specifications: ABNF", RFC 2234, November 1997. 1132 [RFC2244] Newman, C. and J. Myers, "ACAP -- Application 1133 Configuration Access Protocol", RFC 2244, November 1997. 1135 [RFC3282] Alvestrand, H., "Content Language Headers", RFC 3282, 1136 May 2002. 1138 [RFC3501] Crispin, M., "INTERNET MESSAGE ACCESS PROTOCOL - VERSION 1139 4rev1", RFC 3501, March 2003. 1141 [RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO 1142 10646", STD 63, RFC 3629, November 2003. 1144 8.2. Informative References 1146 [I-D.ietf-imapext-annotate] 1147 Gellens, R. and C. Daboo, "IMAP ANNOTATE Extension", 1148 draft-ietf-imapext-annotate-13 (work in progress), 1149 April 2005. 1151 Appendix A. Acknowledgments 1153 The ideas expressed in this document are based on the message 1154 annotation document that was co-authored by Randall Gellens. The 1155 participants of the IMAPext working group made significant 1156 contributions to this work. 1158 Author's Address 1160 Cyrus Daboo 1162 Email: cyrus@daboo.name 1164 Intellectual Property Statement 1166 The IETF takes no position regarding the validity or scope of any 1167 Intellectual Property Rights or other rights that might be claimed to 1168 pertain to the implementation or use of the technology described in 1169 this document or the extent to which any license under such rights 1170 might or might not be available; nor does it represent that it has 1171 made any independent effort to identify any such rights. Information 1172 on the procedures with respect to rights in RFC documents can be 1173 found in BCP 78 and BCP 79. 1175 Copies of IPR disclosures made to the IETF Secretariat and any 1176 assurances of licenses to be made available, or the result of an 1177 attempt made to obtain a general license or permission for the use of 1178 such proprietary rights by implementers or users of this 1179 specification can be obtained from the IETF on-line IPR repository at 1180 http://www.ietf.org/ipr. 1182 The IETF invites any interested party to bring to its attention any 1183 copyrights, patents or patent applications, or other proprietary 1184 rights that may cover technology that may be required to implement 1185 this standard. Please address the information to the IETF at 1186 ietf-ipr@ietf.org. 1188 Disclaimer of Validity 1190 This document and the information contained herein are provided on an 1191 "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS 1192 OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY AND THE INTERNET 1193 ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS OR IMPLIED, 1194 INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE 1195 INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED 1196 WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. 1198 Copyright Statement 1200 Copyright (C) The Internet Society (2005). This document is subject 1201 to the rights, licenses and restrictions contained in BCP 78, and 1202 except as set forth therein, the authors retain all their rights. 1204 Acknowledgment 1206 Funding for the RFC Editor function is currently provided by the 1207 Internet Society.