idnits 2.17.1 draft-daboo-imap-annotatemore-02.txt: ** The Abstract section seems to be numbered Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- ** Looks like you're using RFC 2026 boilerplate. This must be updated to follow RFC 3978/3979, as updated by RFC 4748. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- ** The document seems to lack a 1id_guidelines paragraph about the list of Shadow Directories. == No 'Intended status' indicated for this document; assuming Proposed Standard Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** The document seems to lack an Introduction section. ** There are 19 instances of too long lines in the document, the longest one being 8 characters in excess of 72. ** There are 4 instances of lines with control characters in the document. ** The abstract seems to contain references ([IMAP4]), which it shouldn't. Please replace those with straight textual mentions of the documents in question. 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 the recommended RFC 2119 boilerplate, even if it appears to use RFC 2119 keywords. (The document does seem to have the reference to RFC 2119 which the ID-Checklist requires). -- 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 (March 2003) is 7710 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) ** Obsolete normative reference: RFC 2234 (ref. 'ABNF') (Obsoleted by RFC 4234) ** Obsolete normative reference: RFC 2060 (ref. 'IMAP4') (Obsoleted by RFC 3501) ** Obsolete normative reference: RFC 2192 (ref. 'IMAPURL') (Obsoleted by RFC 5092) == Outdated reference: A later version (-20) exists of draft-ietf-imapext-sort-10 -- Possible downref: Normative reference to a draft: ref. 'THREAD' == Outdated reference: A later version (-16) exists of draft-ietf-imapext-annotate-05 Summary: 10 errors (**), 0 flaws (~~), 5 warnings (==), 4 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 1 Network Working Group C. Daboo 2 Internet Draft: IMAP ANNOTATEMORE Extension 3 Document: draft-daboo-imap-annotatemore-02.txt March 2003 5 IMAP ANNOTATEMORE Extension 7 Status of this Memo 9 This document is an Internet-Draft and is in full conformance with 10 all provisions of Section 10 of RFC2026. 12 Internet-Drafts are working documents of the Internet Engineering 13 Task Force (IETF), its areas, and its working groups. Note that 14 other groups may also distribute working documents as 15 Internet-Drafts. 17 Internet-Drafts are draft documents valid for a maximum of six 18 months and may be updated, replaced, or obsoleted by other documents 19 at any time. It is inappropriate to use Internet-Drafts as 20 reference material or to cite them other than as "work in progress." 22 The list of current Internet-Drafts can be accessed at 23 http://www.ietf.org/ietf/1id-abstracts.txt. 25 The list of Internet- Draft Shadow Directories can be accessed at 26 http://www.ietf.org/shadow.html. 28 Copyright Notice 30 Copyright (C) The Internet Society 2003. All Rights Reserved. 32 Table of Contents 33 1 Abstract . . . . . . . . . . . . . . . . . . . . . . . . . . 2 34 2 Conventions Used in This Document . . . . . . . . . . . . . 2 35 3 Open Issues: . . . . . . . . . . . . . . . . . . . . . . . . 2 36 4 Change History . . . . . . . . . . . . . . . . . . . . . . . 3 37 5 Introduction and Overview . . . . . . . . . . . . . . . . . . 3 38 6 Data Model . . . . . . . . . . . . . . . . . . . . . . . . . 4 39 6.1 Overview . . . . . . . . . . . . . . . . . . . . . . . . 4 40 6.2 Namespace of entries and attributes . . . . . . . . . . 4 41 6.2.1 Entry Names . . . . . . . . . . . . . . . . . . . . . 5 42 6.2.1.1 Server Entries . . . . . . . . . . . . . . . . . 5 43 6.2.1.2 Mailbox Entries . . . . . . . . . . . . . . . . . 5 44 6.2.2 Attribute Names . . . . . . . . . . . . . . . . . . 7 45 7 Private versus Shared and Access Control . . . . . . . . . . 7 46 8 IMAP Protocol Changes . . . . . . . . . . . . . . . . . . . 8 47 8.1 GETANNOTATION Command . . . . . . . . . . . . . . . . . . 8 48 8.2 SETANNOTATION command . . . . . . . . . . . . . . . . . 9 49 8.3 ANNOTATION Response . . . . . . . . . . . . . . . . . . . 11 50 8.3.1 ANNOTATION response with attributes and values . . . 11 51 8.3.2 Unsolicited ANNOTATION response without attributes an 12 52 9 Formal Syntax . . . . . . . . . . . . . . . . . . . . . . . 12 53 10 IANA Considerations . . . . . . . . . . . . . . . . . . . . . 13 54 10.1 Entry and Attribute Registration Template . . . . . . . 14 55 11 Security Considerations . . . . . . . . . . . . . . . . . . . 14 56 12 Normative References . . . . . . . . . . . . . . . . . . . . 14 57 13 Informative References . . . . . . . . . . . . . . . . . . . 15 58 14 Acknowledgments . . . . . . . . . . . . . . . . . . . . . . 15 59 15 Author's Address . . . . . . . . . . . . . . . . . . . . . . 15 60 16 Full Copyright Statement . . . . . . . . . . . . . . . . . . 15 62 1 Abstract 64 The ANNOTATEMORE extension to the Internet Message Access Protocol 65 [IMAP4] permits clients and servers to maintain "metadata" on IMAP4 66 servers. This document describes two "profiles" for mailbox and 67 server metadata. 69 2 Conventions Used in This Document 71 The key words "REQUIRED", "MUST", "MUST NOT", "SHOULD", "SHOULD 72 NOT", and "MAY" in this document are to be interpreted as described 73 in "Key words for use in RFCs to Indicate Requirement Levels" 74 [KEYWORDS]. 76 Formal syntax is defined using ABNF [ABNF] as modified by [IMAP4]. 78 In examples, "C:" and "S:" indicate lines sent by the client and 79 server respectively. 81 3 Open Issues: 83 1 Handling of failures in SETANNOTATION with multiple mailbox 84 entries specified, and at least one fails but others succeed. 86 2 Do we want explicit access control for the /server hierarchy, 87 beyond simply defining certain attributes as read-only in the spec? 89 3 Should mailbox name in entry use IMAPURL encoding or should it 90 be pure UTF8? 92 4 SETANNOTATION does not currently implement conditional store 93 behaviour. Do we want this? 95 5 Should LIST flags, mailbox referrals, STATUS info be attributes 96 of the /mailbox annotations? 98 6 Do we want the ability to search for annotations in the /server 99 or /mailbox hierarchies? 101 4 Change History 103 Todo from -01 to -02: 104 1. SETANNOTATION lists use (..). 105 2. Explicitly state behaviour of unsolicited responses. 106 3. Adding SHOULD behaviour for rename/delete of mailboxes. 107 4. Added statement about supporting annotations on \Noselect mailboxes. 108 5. Cleaned up formal syntax to use IMAP string type for entry 109 and attributes, with requirements on how the string is formatted. 110 6. Use of ACAP vendor subtree registry for vendor tokens. 112 Changes from -00 to -01: 113 1. Multiple entry-att responses are now simply delimited by 114 spaces in line with ANNOTATE spec. Adjusted examples to match. 115 2. Fixed entry-list formal syntax item to account for unsolicited 116 parenthesised list of entries. 117 3. Removed setentries formal syntax item for simplicity since 118 its only used once. 119 4. Removed reference to 'message annotation' in section 5.1. 120 5. Changed formal syntax to restrict top level entries to 121 /server and /mailbox/{...} only. Re-arranged entry names 122 section to account for this change. 123 6. Added comment and example for ANNOTATION response to allow 124 servers to return separate responses for each entry if desired. 126 5 Introduction and Overview 128 The ANNOTATEMORE extension is present in any IMAP4 implementation 129 which returns "ANNOTATEMORE" as one of the supported capabilities in 130 the CAPABILITY command response. 132 The goal of ANNOTATEMORE is to provide a means for clients to store 133 and retrieve "metadata" on an IMAP4 server. This draft defines 134 "profiles" for storing metadata associated with specific mailboxes 135 and the server as a whole. 137 The ANNOTATEMORE extension adds two new commands and one new 138 untagged response to the IMAP4 base protocol. 140 This extension makes the following changes to the IMAP4 protocol: 142 a adds a new SETANNOTATION command 143 b adds a new GETANNOTATION command 144 c adds a new ANNOTATION untagged response 146 The data model used in ANNOTATEMORE is exactly the same as that used 147 in the ANNOTATE [ANNOTATE] extension to IMAP4. This is modeled 148 after that of the Application Configuration Access Protocol [ACAP] 149 with the exception of inheritance which is not deemed necessary 150 here. 152 The rest of this document describes the data model and protocol 153 changes more rigorously. 155 6 Data Model 157 6.1 Overview 159 The data model used in ANNOTATEMORE is one of a uniquely named entry 160 with a set of uniquely named attributes, each of which has a value. 161 An annotation can contain multiple named entries. For example, a 162 general comment being added to a mailbox may have an entry name of 163 "/mailbox/{INBOX}/comment". This entry could include named 164 attributes such as "value", "modifiedsince", "acl" etc to represent 165 properties and data associated with the entry. 167 The protocol changes to IMAP described below allow a client to 168 access or change the values of any attributes in any entries in an 169 annotation, assuming it has sufficient access rights to do so. 171 6.2 Namespace of entries and attributes 173 Each annotation is made up of a set of entries. Each entry has a 174 hierarchical name in UTF-8, with each component of the name 175 separated by a slash ("/"). 177 Each entry is made up of a set of attributes. Each attribute has a 178 hierarchical name in UTF-8, with each component of the name 179 separated by a period ("."). 181 The value of an attribute is NIL (has no value), or a string of zero 182 or more octets. 184 Entry and attribute names are not permitted to contain asterisk 185 ("*") or percent ("%") characters and MUST be valid UTF-8 strings 186 which do not contain NUL. Invalid entry or attribute names result 187 in a BAD response in any IMAP commands where they are used. 189 Use of non-visible UTF-8 characters in entry and attribute names is 190 discouraged. 192 This specification defines an initial set of entry and attribute 193 names available for use with mailbox and server annotations. In 194 addition an extension mechanism is described to allow additional 195 names to be added for extensibility. 197 6.2.1 Entry Names 199 Entry names MUST be specified in a standards track or IESG approved 200 experimental RFC, or fall under the vendor namespace. See Section 201 10.1 for the registration template. This specification only allows 202 two top-level entry types for servers and mailboxes. 204 6.2.1.1 Server Entries 206 /server 207 Defines the top-level of entries associated with the server. 208 This entry itself cannot be accessed directly. 210 /server/comment 211 Defines a comment or note associated with the server. 213 /server/motd 214 Defines a "message of the day" for the server. This entry is 215 always read-only - clients cannot change it. 217 /server/admin 218 Indicates a method for contacting the server administrator. 219 This may be a URL (e.g. a mailto URL) or other contact 220 information, such as a telephone number. This entry is always 221 read-only - clients cannot change it. 223 /server/vendor/ 224 Defines the top-level of entries associated with the server as 225 created by a particular product of some vendor. This entry can 226 be used by vendors to provide server or client specific 227 attributes. The vendor-token MUST be registered with IANA, 228 using the [ACAP] vendor subtree registry. 230 6.2.1.2 Mailbox Entries 232 Servers SHOULD ensure that mailbox annotations are automatically 233 renamed when the mailbox they refer to is renamed, i.e. the 234 annotations follow the mailbox. Servers SHOULD delete annotations 235 for a mailbox when the mailbox is deleted, so that a mailbox created 236 with the same name as a previously existing mailbox does not inherit 237 the old mailbox annotations. Servers SHOULD allow annotations on 238 all 'types' of mailbox, including ones reporting \Noselect for their 239 LIST response. 241 /mailbox 242 Defines the top-level of entries associated with mailboxes. 243 This entry itself cannot be accessed directly. 245 /mailbox/{} 246 Defines the top-level of entries associated with a specific 247 mailbox. The is the name of the mailbox encoded 248 using the mailbox name encoding rules described in the IMAP URL 249 standard [IMAPURL]. The mailbox name appears inside 250 curly-braces to delimit it from the following levels of entry 251 name hierarchy, since it is possible that the mailbox name 252 itself contains the '/' characters used to delimit entry name 253 hierarchical components. Curly-braces are used as delimiters 254 because those characters cannot appear in the encoded URL 255 string, they can only be represented by a '%xx' escaped 256 character sequence in the URL. This entry itself cannot be 257 accessed directly. 259 Note, that whilst entry names are case insensitive, the 260 portion is case-senstive if the server uses case 261 sensitive mailbox names. 263 /mailbox/{}/comment 264 Defines a comment or note associated with a mailbox. 266 /mailbox/{}/sort 267 Defines the default sort criteria [SORT] to use when first 268 displaying the mailbox contents to the user, or NIL if sorting 269 is not required. 271 /mailbox/{}/thread 272 Defines the default thread criteria [THREAD] to use when first 273 displaying the mailbox contents to the user, or NIL if threading 274 is not required. If both sort and thread are not NIL, then 275 threading should take precedence over sorting. 277 /mailbox/{}/check 278 Boolean value "true" or "false" that indicates whether this 279 mailbox should be checked at regular intervals by the client. 280 The interval in minutes is specified by the checkperiod 281 attribute. 283 /mailbox/{}/checkperiod 284 Numeric value indicating a period of minutes to use for checking 285 a mailbox that has the check attribute set to "true". 287 /mailbox/{}/vendor/ 288 Defines the top-level of entries associated with a specific 289 mailbox as created by a particular product of some vendor. This 290 entry can be used by vendors to provide client specific 291 attributes. The vendor-token MUST be registered with IANA, 292 using the [ACAP] vendor subtree registry. 294 6.2.2 Attribute Names 296 Attribute names MUST be specified in a standards track or IESG 297 approved experimental RFC, or fall under the vendor namespace. See 298 Section 10.1 for the registration template. 300 All attribute names implicitly have a ".priv" and a ".shared" suffix 301 which maps to private and shared versions of the entry. Searching 302 or fetching without using either suffix includes both. The client 303 MUST specify either a ".priv" or ".shared" suffix when storing an 304 annotation. 306 value 307 The data value of the attribute. 309 size 310 The size of the value, in octets. Set automatically by the 311 server, read-only to clients. 313 modifiedsince 314 An opaque value set by the server when this entry is modified. 315 It can be used by the client to request notification of which 316 entries have changed since a particular point in time and is 317 useful for disconnected/synchronisation operations. 319 content-type 320 A MIME [MIME] content type and subtype that describes the nature 321 of the content of the "value" attribute. 323 vendor. 324 Defines an attribute associated with a particular product of 325 some vendor. This attribute can be used by vendors to provide 326 client specific attributes. The vendor-token MUST be registered 327 with IANA, using the [ACAP] vendor subtree registry. 329 7 Private versus Shared and Access Control 331 As discussed in the ANNOTATE extension [ANNOTATE] there is a need to 332 support both private and shared annotations. This document adopts 333 the scheme used in [ANNOTATE] that adds two standard suffixes for 334 all attributes: ".shared" and ".priv". A GETANNOTATION command 335 which specifies neither uses both. SETANNOTATION commands MUST 336 explicitly use .priv or .shared suffixes. 338 A user can only store and retrieve private annotations on a mailbox 339 which is returned to them via a LIST or LSUB command. A user can 340 only store and retrieve shared annotations on a mailbox that they 341 can SELECT and which opens READ-WRITE. If a client attempts to 342 store or retrieve a shared annotation on a READ-ONLY mailbox, the 343 server MUST respond with a NO response. 345 8 IMAP Protocol Changes 347 8.1 GETANNOTATION Command 349 This extension adds the GETANNOTATION command. This allows clients 350 to retrieve annotations. 352 This command is only available in authenticated state [IMAP4]. 354 Arguments: entry-specifier 355 attribute-specifier 357 Responses: required ANNOTATION response 359 Result: OK - command completed 360 NO - command failure: can't access annotations on that mailbox 361 BAD - command unknown or arguments invalid 363 Example: 365 C: a GETANNOTATION "/server/comment" "value.priv" 366 S: * ANNOTATION "/server/comment" ("value.priv" "My comment") 367 S: a OK GETANNOTATION complete 369 In the above example, the contents of the "value" attribute 370 for the "/server/comment" entry is requested by the client 371 and returned by the server. 373 "*" and "%" wildcard characters can be used in either specifier to 374 match one or more characters at that position, with the exception 375 that "%" does not match the hierarchy delimiter for the specifier it 376 appears in (i.e. "/" for an entry specifier or "." for an attribute 377 specifier). Thus an entry specifier of "/server/%" would match 378 entries such as "/server/comment" and "/server/version", but not 379 "/server/comment/note". 381 Examples: 383 C: a GETANNOTATION "/server/*" "value.priv" 384 S: * ANNOTATION "/server/comment" ("value.priv" "My comment") 385 "/server/version" ("value.priv" "1.1") 386 "/server/motd/today" ("value.priv" "Closed at 1 pm") 387 S: a OK GETANNOTATION complete 388 In the above example, the contents of the "value" attributes 389 for any entries in the "/server" hierarchy are requested by 390 the client and returned by the server. 392 C: a GETANNOTATION "/server/%" "value" 393 S: * ANNOTATION "/server/comment" ("value.priv" "My comment") 394 ("value.shared" "Your comment") 395 "/server/motd" ("value.priv" "Its sunny outside!" 396 ("value.shared" "Today is a Holiday") 397 S: a OK GETANNOTATION complete 399 In the above example, the contents of the "value" attributes 400 for entries at the top level of the "/server" hierarchy 401 only, are requested by the client and returned by the 402 server. Both the .priv and .shared values are returned, as 403 neither were explicitly requested. 405 Entry and attribute specifiers can be lists of atomic specifiers, so 406 that multiple items of each type may be returned in a single 407 GETANNOTATION command. 409 Examples: 411 C: a GETANNOTATION ("/server/comment" "/server/motd") "value.priv" 412 S: * ANNOTATION "/server/comment" ("value.priv" "My comment") 413 "/server/motd" ("value.priv" "Its sunny outside!") 414 S: a OK GETANNOTATION complete 416 In the above example, the contents of the "value" attributes 417 for the two entries "/server/comment" and "/server/motd" are 418 requested by the client and returned by the server. 420 C: a GETANNOTATION "/server/comment" ("value.priv" "modifiedsince.priv") 421 S: * ANNOTATION "/server/comment" 422 ("value.priv" "My comment" 423 "modifiedsince.priv" "19990203205432") 424 S: a OK GETANNOTATION complete 426 In the above example, the contents of the "value" and 427 "modifiedsince" attributes for the "/server/comment" entry 428 are requested by the client and returned by the server. 430 8.2 SETANNOTATION command 432 This extension adds the SETANNOTATION command. This allows clients 433 to set annotations. 435 This command is only available in authenticated state [IMAP4]. 437 Arguments: entry 438 attribute-value 439 list of entry, attribute-values 440 Responses: no specific responses for this command 442 Result: OK - command completed 443 NO - command failure: can't set annotations 444 BAD - command unknown or arguments invalid 446 Sets the specified list of entries by adding or replacing the 447 specified attributes with the values provided. Clients can use NIL 448 for values of attributes it wants to remove from entries. The 449 server MAY return an unsolicited ANNOTATION response containing the 450 updated annotation data. The server SHOULD send such responses for 451 any changes to the /server annotations, and SHOULD send such 452 responses for /mailbox only for the currently selected mailbox. 453 Clients MUST NOT assume that an unsolicited ANNOTATION response will 454 be sent, and MUST assume that if the command succeeds then the 455 annotation has been changed. 457 Examples: 459 C: a SETANNOTATION "/mailbox/{INBOX}/comment" 460 ("value.priv" "My new comment") 461 S: a OK SETANNOTATION complete 463 In the above example, the entry "/mailbox/{INBOX}/comment" 464 is created (if not already present) and the private 465 attribute "value" with data set to "My new comment" is 466 created if not already present, or replaced if it previously 467 exists. 469 C: a SETANNOTATION "/mailbox/{INBOX}/comment" ("value.priv" NIL) 470 S: a OK SETANNOTATION complete 472 In the above example, the private "value" attribute of the 473 entry "/mailbox/{INBOX}/comment" is removed. 475 Multiple entries can be set in a single SETANNOTATION command by 476 listing entry-attribute-value pairs in the list. 478 Example: 479 C: a SETANNOTATION ("/mailbox/{INBOX}/comment" 480 ("value.priv" "My new comment") 481 "/mailbox/{INBOX.shared}/comment" 482 ("value.shared" "This is a shared mailbox")) 483 S: a OK SETANNOTATION complete 485 In the above example, the entries "/mailbox/{INBOX}/comment" 486 and "/mailbox/{INBOX.shared}/comment" are created (if not 487 already present) and the private and shared attributes 488 "value" are created respectively for each entry if not 489 already present, or replaced if they previously existed. 491 Multiple attributes can be set in a single SETANNOTATION command by 492 listing multiple attribute-value pairs in the entry list. 494 Example: 495 C: a SETANNOTATION "/mailbox/{INBOX}/comment" 496 ("value.priv" "My new comment" 497 "vendor.foobar.bloop.priv" "foo's bar") 498 S: a OK SETANNOTATION complete 500 In the above example, the entry "/mailbox/{INBOX}/comment" 501 is created (if not already present) and the private 502 attributes "value" and "vendor.foobar.bloop" are created if 503 not already present, or replaced if they previously existed. 505 8.3 ANNOTATION Response 507 The ANNOTATION response displays results of a GETANNOTATION command, 508 or can be returned as a unsolicited response at anytime by the 509 server in response to a change in an annotation. 511 Servers SHOULD send unsolicited ANNOTATION responses for /server and 512 for /mailbox, provided the mailbox associated with that annotation 513 is the one currently selected, if changed by a third-party, allowing 514 servers to keep clients updated with changes to annotations by other 515 clients. In this case, only the entries are returned in the 516 ANNOTATION response, not the attributes and values. If the client 517 wants to update any cached values it must explicitly retrieve those 518 using a GETANNOTATION command. 520 The ANNOTATION response can contain multiple entries in a single 521 response, but the server is free to return multiple responses for 522 each entry or group of entries if it desires. 524 This response is only available in authenticated state [IMAP4]. 526 8.3.1 ANNOTATION response with attributes and values 527 The response consists of a list of entries each of which has a 528 list of attribute-value pairs. 530 Examples: 532 C: a GETANNOTATION "/server/comment" "value.priv" 533 S: * ANNOTATION "/server/comment" ("value.priv" "My comment") 534 S: a OK GETANNOTATION complete 536 In the above example, a single entry with a single 537 attribute-value pair is returned by the server. 539 C: a GETANNOTATION ("/server/comment" "/server/motd") "value.priv" 540 S: * ANNOTATION "/server/comment" ("value.priv" "My comment") 541 "/server/motd" ("value.priv" "Its sunny outside!") 542 S: a OK GETANNOTATION complete 543 In the above example, two entries each with a single 544 attribute-value pair is returned by the server. 546 C: a GETANNOTATION ("/server/comment" "/server/motd") "value.priv" 547 S: * ANNOTATION "/server/comment" ("value.priv" "My comment") 548 S: * ANNOTATION "/server/motd" ("value.priv" "Its sunny outside!") 549 S: a OK GETANNOTATION complete 551 In the above example, the server returns two separate 552 response for each of the two entries requested. 554 C: a GETANNOTATION "/server/comment" ("value.priv" "modifiedsince.priv") 555 S: * ANNOTATION "/server/comment" ("value.priv" "My comment" 556 "modifiedsince.priv" "19990203205432") 557 S: a OK GETANNOTATION complete 559 In the above example, a single entry with two 560 attribute-value pairs is returned by the server. 562 8.3.2 Unsolicited ANNOTATION response without attributes and values 563 The response consists of a parenthesised list of entries, each 564 of which have changed on the server. 566 Examples: 568 C: a NOOP 569 S: * ANNOTATION ("/server/comment") 570 S: a OK NOOP complete 572 In the above example, the server indicates that the 573 "/server/comment" entry has been changed. 575 C: a NOOP 576 S: * ANNOTATION ("/server/comment" "/server/motd") 577 S: a OK NOOP complete 579 In the above example, the server indicates a change to two 580 entries. 582 9 Formal Syntax 584 The following syntax specification uses the Augmented Backus-Naur 585 Form (ABNF) notation as specified in [ABNF]. 587 Non-terminals referenced but not defined below are as defined by 588 [IMAP4]. 590 Except as noted otherwise, all alphabetic characters are case- 591 insensitive. The use of upper or lower case characters to define 592 token strings is for editorial clarity only. Implementations MUST 593 accept these strings in a case-insensitive fashion. 595 command-auth /= setannotation / getannotation 596 ; adds to original IMAP4 command 598 response-data /= "*" SP annotate-data CRLF 599 ; adds to original IMAP4 data responses 601 getannotation = "GETANNOTATION" SP entries SP attribs 602 ; new command 604 setannotation = "SETANNOTATION" SP setentryatt 605 ; new command 607 annotate-data = "ANNOTATION" SP entry-list 608 ; new response 610 entries = entry-match / "(" entry-match *(SP entry-match) ")" 611 ; entry specifiers that can include wildcards 613 attribs = attrib-match / "(" attrib-match *(SP attrib-match) ")" 614 ; attribute specifiers that can include wildcards 616 entry-list = entry-att *(SP entry-att) / 617 "(" entry *(SP entry) ")" 618 ; entry attribute-value pairs list for 619 ; GETANNOTATION response, or 620 ; parenthesised entry list for unsolicited 621 ; notification of annotation changes 623 setentryatt = entry-att / "(" entry-att *(SP entry-att) ")" 624 entry-att = entry SP "(" att-value *(SP att-value) ")" 625 att-value = attrib SP value 627 entry = string 628 ; slash-separated path to entry 629 ; begins with "/server/" or "/mailbox/" 630 ; MUST NOT contain "*" or "%" 631 entry-match = string 632 ; slash-separated path to entry 633 ; begins with "/server/" or "/mailbox/" 634 ; MAY contain "*" or "%" for use as wildcards 636 attrib = string 637 ; dot-separated attribute name 638 ; MUST NOT contain "*" or "%" 639 attrib-match = string 640 ; dot-separated attribute name 641 ; MAY contain "*" or "%" for use as wildcards 643 value = nstring 644 10 IANA Considerations 646 Both entry names and attribute names MUST be specified in a 647 standards track or IESG approved experimental RFC, or fall under the 648 vendor namespace. 650 10.1 Entry and Attribute Registration Template 652 To: iana@iana.org 653 Subject: IMAP Annotate More Registration 655 Please register the following IMAP Annotate More item: 657 [] Entry [] Attribute 659 Name: ______________________________ 661 Description: _______________________ 663 ____________________________________ 665 ____________________________________ 667 Contact person: ____________________ 669 email: ____________________ 671 11 Security Considerations 673 The ANNOTATEMORE extension does not raise any security 674 considerations that are not present in the base [IMAP4] protocol, 675 and these issues are discussed in [IMAP4]. 677 Care must be taken to ensure that annotations whose values are 678 intended to remain private are not stored in mailboxes which are 679 accessible to other users. This includes mailboxes owned by the 680 user by whose ACLs permit access by others as well as any shared 681 mailboxes. 683 12 Normative References 685 [ABNF] Crocker, Overell, "Augmented BNF for Syntax Specifications: 686 ABNF", RFC 2234, Internet Mail Consortium, Demon Internet Ltd, 687 November 1997. 689 [ACAP] Newman, C., and Myers, J. "ACAP -- Application Configuration 690 Access Protocol", RFC 2244, November 1997. 692 [IMAP4] Crispin, M., "Internet Message Access Protocol - Version 693 4rev1", RFC 2060, University of Washington, December 1996. 695 [IMAPURL] Newman, C., "IMAP URL Scheme", RFC 2192, Innosoft, 696 September 1997. 698 [KEYWORDS] Bradner, "Key words for use in RFCs to Indicate 699 Requirement Levels", RFC 2119, Harvard University, March 1997. 701 [MIME] Freed, N., and Borenstein, N. "MIME (Multipurpose Internet 702 Mail Extensions) Part Two: Media Types", RFC 2046, November 1996. 704 [SORT] Crispin, M., Murchison, K., "Internet Message Access Protocol 705 - Sort Extension", draft-ietf-imapext-sort-10.txt, University of 706 Washington, Oceana Matrix Ltd., October 2002. 708 [THREAD] Crispin, M., Murchison, K., "Internet Message Access 709 Protocol - Thread Extension", draft-ietf-imapext-thread-12.txt, 710 University of Washington, Oceana Matrix Ltd., October 2001. 712 13 Informative References 714 [ANNOTATE] Daboo, C., Gellens, R., "IMAP ANNOTATE Extension", 715 draft-ietf-imapext-annotate-05.txt, November 2002. 717 14 Acknowledgments 719 The ideas expressed in this document are based on the message 720 annotation document that was co-authored by Randall Gellens. 722 15 Author's Address 724 Cyrus Daboo 725 Cyrusoft International, Inc. 726 Suite 780, 5001 Baum Blvd. 727 Pittsburgh, PA 15213 728 U.S.A. 730 Email: daboo@cyrusoft.com 732 16 Full Copyright Statement 734 Copyright (C) The Internet Society 2003. All Rights Reserved. 736 This document and translations of it may be copied and furnished to 737 others, and derivative works that comment on or otherwise explain it 738 or assist in its implementation may be prepared, copied, published 739 and distributed, in whole or in part, without restriction of any 740 kind, provided that the above copyright notice and this paragraph 741 are included on all such copies and derivative works. However, this 742 document itself may not be modified in any way, such as by removing 743 the copyright notice or references to the Internet Society or other 744 Internet organizations, except as needed for the purpose of 745 developing Internet standards in which case the procedures for 746 copyrights defined in the Internet Standards process must be 747 followed, or as required to translate it into languages other than 748 English. 750 The limited permissions granted above are perpetual and will not be 751 revoked by the Internet Society or its successors or assigns. 753 This document and the information contained herein is provided on an 754 "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING 755 TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING 756 BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION 757 HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF 758 MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.