idnits 2.17.1 draft-ietf-imapext-annotate-00.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 Internet-Drafts being working documents. == 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. ** The document seems to lack separate sections for Informative/Normative References. All references will be assumed normative when checking for downward references. ** There is 1 instance of too long lines in the document, the longest one being 3 characters in excess of 72. ** 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 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 (July 2000) is 8685 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: 'MIME' is mentioned on line 317, but not defined ** Obsolete normative reference: RFC 2234 (ref. 'ABNF') (Obsoleted by RFC 4234) ** Obsolete normative reference: RFC 2086 (ref. 'ACL-EXT') (Obsoleted by RFC 4314) ** Obsolete normative reference: RFC 2060 (ref. 'IMAP4') (Obsoleted by RFC 3501) ** Obsolete normative reference: RFC 1891 (ref. 'SMTP-DSN') (Obsoleted by RFC 3461) -- Possible downref: Non-RFC (?) normative reference: ref. 'SORT-EXT' Summary: 11 errors (**), 0 flaws (~~), 3 warnings (==), 4 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 1 IMAP Extensions Working Group R. Gellens 2 Internet Draft: IMAP ANNOTATE Extension C. Daboo 3 Document: draft-ietf-imapext-annotate-00.txt July 2000 5 IMAP ANNOTATE 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. Internet-Drafts are 11 working documents of the Internet Engineering Task Force (IETF), its 12 areas, and its working groups. Note that other groups may also 13 distribute working documents as Internet-Drafts. 15 Internet-Drafts are draft documents valid for a maximum of six 16 months and may be updated, replaced, or obsoleted by other documents 17 at any time. It is inappropriate to use Internet-Drafts as 18 reference material or to cite them other than as "work in progress." 20 The list of current Internet-Drafts can be accessed at 21 http://www.ietf.org/ietf/1id-abstracts.txt. The list of Internet- 22 Draft Shadow Directories can be accessed at 23 http://www.ietf.org/shadow.html. 25 Copyright Notice 27 Copyright (C) The Internet Society 2000. All Rights Reserved. 29 Table of Contents 30 1 Abstract . . . . . . . . . . . . . . . . . . . . . . . . . . 2 31 2 Discussion . . . . . . . . . . . . . . . . . . . . . . . . . 2 32 3 Conventions Used in This Document . . . . . . . . . . . . . . 2 33 4 Document Meta-Data . . . . . . . . . . . . . . . . . . . . . 3 34 4.1 Open Issues . . . . . . . . . . . . . . . . . . . . . . . 3 35 4.2 Change History . . . . . . . . . . . . . . . . . . . . . 3 36 5 Introduction and Overview . . . . . . . . . . . . . . . . . . 3 37 6 Data Model . . . . . . . . . . . . . . . . . . . . . . . . . 4 38 6.1 Overview . . . . . . . . . . . . . . . . . . . . . . . . 4 39 6.2 Namespace of Entries and Attributes . . . . . . . . . . 5 40 6.2.1 Entry Names . . . . . . . . . . . . . . . . . . . . . 5 41 6.2.2 Attribute Names . . . . . . . . . . . . . . . . . . 7 42 7 Private vs. Non-Private . . . . . . . . . . . . . . . . . . . 7 43 8 IMAP Protocol Changes . . . . . . . . . . . . . . . . . . . 8 44 8.1 ANNOTATION Message Data Item in FETCH Command . . . . . . 8 45 8.2 ANNOTATION Message Data Item in FETCH Response . . . . . 10 46 8.3 ANNOTATION Message Data Item in STORE . . . . . . . . . . 11 47 8.3.1 Conditional Annotation STORE . . . . . . . . . . . . 12 48 8.4 ANNOTATION Message Data Item in APPEND . . . . . . . . . 12 49 8.5 ANNOTATION-MODTIME Message Data Item in STATUS . . . . . 13 50 8.6 ANNOTATION Criterion in SEARCH . . . . . . . . . . . . . 13 51 8.7 ANNOTATION Key in SORT . . . . . . . . . . . . . . . . . 14 52 8.8 Annotation Modtime Untagged Response . . . . . . . . . . 14 53 8.9 ACL Rights . . . . . . . . . . . . . . . . . . . . . . . 15 54 9 Formal Syntax . . . . . . . . . . . . . . . . . . . . . . . . 15 55 10 IANA Considerations . . . . . . . . . . . . . . . . . . . . 16 56 10.1 Entry and Attribute Registration Template . . . . . . . . 17 57 11 Security Considerations . . . . . . . . . . . . . . . . . . 17 58 12 References . . . . . . . . . . . . . . . . . . . . . . . . . 17 59 13 Acknowledgments . . . . . . . . . . . . . . . . . . . . . . 18 60 14 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . 18 61 15 Full Copyright Statement . . . . . . . . . . . . . . . . . . 18 63 1 Abstract 65 The ANNOTATE extension to the Internet Message Access Protocol 66 [IMAP4] permits clients and servers to maintain "metadata" for 67 messages stored in an IMAP4 mailbox. 69 2 Discussion 71 Public comments can be sent to the IETF IMAP Extensions mailing 72 list, . To subscribe, send a message to 73 with the word SUBSCRIBE as the body. 74 Private comments should be sent to the authors. 76 3 Conventions Used in This Document 77 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 78 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 79 document are to be interpreted as described in RFC 2119 [KEYWORDS]. 81 Formal syntax is defined using ABNF [ABNF] as modified by [IMAP4]. 83 In examples, "C:" and "S:" indicate lines sent by the client and 84 server respectively. Line breaks not preceded by a "C:" or "S:" are 85 for editorial clarity only. 87 4 Document Meta-Data 89 4.1 Open Issues 91 At points in this document open issues are discussed, marked by the 92 text "<<>>". These are items which have not been 93 finalized. Discussion and comment is requested. Please use the 94 IETF IMAP Extensions mailing list, as described in section 95 2. 97 4.2 Change History 99 Changes since -00: 100 1. Clarified text describing attributions, entries, and 101 attributes. 102 2. Changed 'modifiedsince' to 'modtime'; referenced ACAP spec. 103 3. Deleted 'queued' flag. 104 4. Expanded and explained smtp-envelope entry. 105 5. Restricted including ANNOTATION data in unsolicited responses 106 until the client uses it first. (Open issue as to if needed). 107 6. Examples now only use valid entries and attributes. 108 7. Updated Security Considerations. 109 8. Content-Type now defaults to text/plain. 110 9. Open Issue: Shared vs. private annotations. 111 10. Open issue: Annotation Modtime untagged response or VALIDTIME 112 FETCH data. 113 11. Open issue: Conditional annotation STORE. 114 12. ANNOTATION criterion available if both "ANNOTATE" and "SORT" 115 in CAPABILITY command response. 116 13. Prohibition on annotations in lieu of base spec functionality. 117 14. Specified required ACL rights. 118 15. ANNOTATION message data item in APPEND. 119 16. ANNOTATION-MODTIME message data item in STATUS. 120 17. Replaced ATOM_CHAR with utf8-char. 121 18. Updated other ABNF entries. 123 5 Introduction and Overview 125 The ANNOTATE extension is present in any IMAP4 implementation which 126 returns "ANNOTATE" as one of the supported capabilities in the 127 CAPABILITY command response. 129 The ANNOTATE extension adds a new message data item to the FETCH and 130 STORE commands, as well as adding SEARCH and SORT keys and APPEND 131 and STATUS modifiers. 133 This extension makes the following changes to the IMAP4 protocol: 135 a) adds a new ANNOTATION message data item for use in the FETCH 136 command 137 b) adds a new ANNOTATION message data item for use in the STORE 138 command 139 c) adds a new ANNOTATION search criterion for use in the SEARCH 140 command 141 d) adds a new ANNOTATION sort key for use in the SORT command 142 extension 143 e) adds a new ANNOTATION data item for use in the APPEND command 144 f) adds a new ANNOTATION-MODTIME modifier for use in the STATUS 145 command 147 The data model used for the storage of annotations is based on that 148 of the Application Configuration Access Protocol [ACAP]. Note that 149 there is no inheritance in annotations. 151 Clients MUST NOT use annotations in lieu of equivalent IMAP base 152 specification facilities. For example, use of a "seen" flag in the 153 vendor namespace together with ".PEEK" in fetches. Such behavior 154 would significantly reduce IMAP interoperability. 156 The rest of this document describes the data model and protocol 157 changes more rigorously. 159 6 Data Model 161 6.1 Overview 163 The data model used in ANNOTATE is that of a uniquely named entry 164 with a set of uniquely named attributes, each of which has a value. 165 A single coherent unit of "metadata" for a message is stored as a 166 single entry, made up of several attributes. 168 For example, a comment added to a message has an entry name of 169 "/message/comment". This entry is composed of several attributes 170 such as "value", "modtime", etc. which contain the properties and 171 data of the entry. 173 The protocol changes to IMAP described below allow a client to 174 access or change the values of any attributes in any entries in a 175 message annotation, assuming it has sufficient access rights to do 176 so (see section 8.9 for specifics). 178 6.2 Namespace of Entries and Attributes 180 Each message annotation is made up of a set of entries. Each entry 181 has a hierarchical name in UTF-8, with each component of the name 182 separated by a slash ("/"). 184 Each entry is made up of a set of attributes. Each attribute has a 185 hierarchical name in UTF-8, with each component of the name 186 separated by a period ("."). 188 The value of an attribute is NIL (has no value), or a string of zero 189 or more octets. 191 Entry and attribute names are not permitted to contain asterisk 192 ("*") or percent ("%") characters and MUST be valid UTF-8 strings 193 which do not contain NUL. Invalid entry or attribute names result 194 in a BAD response in any IMAP commands where they are used. 196 Use of non-visible UTF-8 characters in entry and attribute names is 197 strongly discouraged. 199 This specification defines an initial set of entry and attribute 200 names available for use in message annotations. In addition, an 201 extension mechanism is described to allow additional names to be 202 added for extensibility. 204 6.2.1 Entry Names 206 Entry names MUST be specified in a standards track or IESG approved 207 experimental RFC, or fall under the vendor namespace. See section 208 10.1 for the registration template. 210 /message 211 Defines the top-level of entries associated with an entire 212 message. This entry itself does not contain any attributes. 214 /message/comment 215 Defines a comment or note associated with an entire message. 217 /message/flags 218 Defines the top-level of entries for client-use flags associated 219 with an entire message. All sub-entries are maintained entirely 220 by the client. There is no implicit change to any flag by the 221 server. 223 /message/flags/redirected 224 /message/flags/forwarded 225 Defines client-use flags for an entire message. The "value" 226 attribute of these entries must be either "1", "0" or NIL. The 227 'redirected' flag indicates that a message has been handed off 228 to someone else, by resending the message with minimal 229 alterations, and in such a way that a reply by the new recipient 230 is addressed to the original author, not the user who performed 231 the redirection. The 'forwarded' flag indicates the message was 232 resent to another user, embedded within or attached to a new 233 message. 235 /message/smtp-envelope 236 Defines the top-level of entries which together describe the 237 SMTP envelope used in delivery of the message. There are no 238 attributes at this level. The client SHOULD NOT modify the 239 /message/smtp-envelope entry or any sub-entries or any of their 240 attributes, except in messages which have the DRAFT flag set. 241 /message/smtp-envelope/from 242 /message/smtp-envelope/to 243 /message/smtp-envelope/orcpt 244 /message/smtp-envelope/envid 245 Contains the properties of the SMTP envelope: 'from' is the 246 return-path of the message; 'to' is the recipient of the 247 message. 'orcpt' and 'envid' contain the original recipient and 248 envelope ID as specified in [SMTP-DSN]. 250 /message/subject 251 Contains text supplied by the message recipient, to be used by 252 the client instead of the original message Subject. 254 /message/vendor/ 255 Defines the top-level of entries associated with an entire 256 message as created by a particular product of some vendor. 257 These sub-entries can be used by vendors to provide 258 client-specific attributes. The vendor-token MUST be registered 259 with IANA. 261 /body/ 262 Defines the top-level of entries associated with a specific body 263 part of a message. This entry itself does not contain any 264 attributes. The part-specifier uses the same part specifier 265 syntax as the BODY message data item in the FETCH command 266 [IMAP4]. 268 /body//comment 269 Defines a comment or note associated with a specific body part 270 of a message. 272 /body//flags 273 Defines the top-level of entries associated with flag state for 274 a specific body part of a message. All sub-entries are 275 maintained entirely by the client. There is no implicit change 276 to any flag by the server. 278 /body//flags/seen 279 /body//flags/answered 280 /body//flags/flagged 281 Defines flags for a specific body part of a message. The 282 "value" attribute of these entries must be either "1", "0" or 283 NIL. 285 /body//vendor/ 286 Defines the top-level of entries associated with a specific body 287 part of a message as created by a particular product of some 288 vendor. This entry can be used by vendors to provide client 289 specific attributes. The vendor-token MUST be registered with 290 IANA. 292 6.2.2 Attribute Names 294 Attribute names MUST be specified in a standards track or IESG 295 approved experimental RFC, or fall under the vendor namespace. See 296 section 10.1 for the registration template. 298 value 299 The data value of the attribute. 301 size 302 The size of the value, in octets. Set automatically by the 303 server, read-only to clients. 305 modtime 306 An opaque value set by the server when this entry is modified. 307 It can be used by the client to request notification of which 308 entries have changed relative to that of a known entry. In 309 addition to its use in disconnected/synchronization operations, 310 it can also be helpful in determining which entries have changed 311 while a client is connected. (The value is intended to be used 312 only for comparisons within a server, not as an accurate 313 timestamp.) It is described more fully in section 3.1.1 of 314 [ACAP]. 316 content-type 317 A MIME [MIME] content type and subtype that describes the nature 318 of the content of the "value" attribute. If not present, a 319 value of "text/plain; charset=utf8" is assumed. 321 vendor. 322 Defines an attribute associated with a particular product of 323 some vendor. This attribute can be used by vendors to provide 324 client specific attributes. The vendor-token MUST be registered 325 with IANA. 327 7 Private vs. Non-Private 328 <<>> 329 Some IMAP mailboxes are private, accessible only to the owning user. 330 Other mailboxes are not, either because the owner has set an ACL 331 [ACL-EXT] which permits access by other users, or because it is a 332 shared mailbox. 334 This raises the issue of shared versus private annotations. 336 If all annotations are private, it is impossible to set annotations 337 in a shared or otherwise non-private mailbox that are visible to 338 other users. This eliminates what could be a useful aspect of 339 annotations in a shared environment. 341 If all annotations are shared, it is impossible to use annotations 342 for private notes on messages in shared mailboxes. Also, modifying 343 an ACL to permit access to a mailbox by other users may 344 unintentionally expose private information. 346 For example, an administrator may want to set shared annotations on 347 messages in a shared folder, which individual users may wish to 348 supplement with additional notes. 350 If shared and private annotations are to coexist, we need a clear 351 way to differentiate them. Also, it should be as easy as possible 352 for a client to access both and not overlook either. 354 One suggestion is to duplicate all attributes, with 'pers.' and 355 'shared.' prefixes. For example, instead of there being one 'size' 356 attribute in an entry, there would be two: 'pers.size' and 357 'shared.size'. Both would be returned by default to the client, to 358 make sure the client didn't miss one. 360 8 IMAP Protocol Changes 362 8.1 ANNOTATION Message Data Item in FETCH Command 364 This extension adds an ANNOTATION message data item to the FETCH 365 command. This allows clients to retrieve annotations for a range of 366 messages in the currently selected mailbox. 368 ANNOTATION 369 The ANNOTATION message data item, when used by the client in the 370 FETCH command, takes an entry specifier and an attribute 371 specifier. 373 Example: 374 C: a FETCH 1 (ANNOTATION ("/message/comment" "value")) 375 S: * 1 FETCH (ANNOTATION ("/message/comment" (("value" 376 "My comment")))) 377 S: a OK Fetch complete 378 In the above example, the content of the "value" attribute for the 379 "/message/comment" entry is requested by the client and returned by 380 the server. 382 "*" and "%" wildcard characters can be used in either specifier to 383 match one or more characters at that position, with the exception 384 that "%" does not match the hierarchy delimiter for the specifier it 385 appears in (that is, "/" for an entry specifier or "." for an 386 attribute specifier). Thus an entry specifier of "/message/%" 387 matches entries such as "/message/comment" and "/message/subject", 388 but not "/message/flags/redirected". 390 Examples: 391 C: a FETCH 1 (ANNOTATION ("/message/*" ("value" "modtime"))) 392 S: * 1 FETCH (ANNOTATION 393 (("/message/comment" ("value" "My comment" 394 "modtime" "20000704000001")) 395 ("/message/subject" ("value" "Rhinoceroses!" 396 "modtime" "19991231235959")) 397 ("/message/vendor/eudora/label" ("value" "label43" 398 "modtime" "20000705101502")) 399 ("/message/vendor/eudora/personality" 400 ("value" "Tallulah Bankhead" 401 "modtime" "20000705101558")))) 402 S: a OK Fetch complete 404 In the above example, the contents of the "value" and "modtime" 405 attributes for any entries in the "/message" hierarchy are requested 406 by the client and returned by the server. 408 C: a FETCH 1 (ANNOTATION ("/message/%" "value")) 409 S: * 1 FETCH (ANNOTATION 410 (("/message/comment" ("value" "Patch Mangler")) 411 ("/message/subject" 412 ("value" "Patches? We don' need no steenkin patches!")))) 413 S: a OK Fetch complete 415 In the above example, the contents of the "value" attributes for 416 entries at the top level only of the "/message" hierarchy are 417 requested by the client and returned by the server. 419 Entry and attribute specifiers can be lists of atomic specifiers, so 420 that multiple items of each type may be returned in a single FETCH 421 command. 423 Examples: 424 C: a FETCH 1 (ANNOTATION 425 (("/message/comment" "/message/subject") "value")) 426 S: * 1 FETCH (ANNOTATION 427 (("/message/comment" ("value" "What a chowder-head")) 428 ("/message/subject" ("value" "How to crush beer cans")))) 429 S: a OK Fetch complete 430 In the above example, the contents of the "value" attributes for the 431 two entries "/message/comment" and "/message/subject" are requested 432 by the client and returned by the server. 434 8.2 ANNOTATION Message Data Item in FETCH Response 436 The ANNOTATION message data item in the FETCH response displays 437 information about annotations in a message. 439 ANNOTATION parenthesised list 440 The response consists of a list of entries, each of which has a 441 list of attribute-value pairs. 443 Examples: 444 C: a FETCH 1 (ANNOTATION ("/message/comment" "value")) 445 S: * 1 FETCH (ANNOTATION ("/message/comment" ( 446 ("value" "My comment")))) 447 S: a OK Fetch complete 449 In the above example, a single entry with a single attribute-value 450 pair is returned by the server. 452 C: a FETCH 1 (ANNOTATION 453 (("/message/comment" "/message/subject") "value")) 454 S: * 1 FETCH (ANNOTATION 455 (("/message/comment" ("value" "My comment")) 456 ("/message/subject" ("value" "My subject")))) 457 S: a OK Fetch complete 459 In the above example, two entries each with a single attribute-value 460 pair are returned by the server. 462 C: a FETCH 1 (ANNOTATION 463 ("/message/comment" ("value" "modtime"))) 464 S: * 1 FETCH (ANNOTATION 465 (("/message/comment" 466 ("value" "My comment" 467 "modtime" "19990203205432")))) 468 S: a OK Fetch complete 470 In the above example, a single entry with two attribute-value pairs 471 is returned by the server. 473 Servers SHOULD send ANNOTATION message data items in unsolicited 474 FETCH responses if the annotation is changed by a third-party, 475 allowing servers to keep clients updated with changes to annotations 476 by other clients. However, servers MUST NOT include ANNOTATION data 477 in unsolicited responses until the client has used ANNOTATION data 478 in a FETCH command. This restriction avoids sending ANNOTATION data 479 to a client until the client has shown it is capable of handling it. 481 <<>> 482 Is this prohibition really neccesary? 484 8.3 ANNOTATION Message Data Item in STORE 486 ANNOTATION 487 Sets the specified list of entries by adding or replacing the 488 specified attributes with the values provided. Clients can use 489 NIL for values of attributes it wants to remove from entries. 491 The ANNOTATION message data item used with the STORE command has an 492 implicit ".SILENT" behavior. This means the server does not 493 generate an untagged FETCH in response to the STORE command and 494 assumes that the client updates its own cache if the command 495 succeeds. 497 Examples: 498 C: a STORE 1 ANNOTATION ("/message/comment" 499 ("value" "My new comment")) 500 S: a OK Store complete 502 In the above example, the entry "/message/comment" is created (if 503 not already present) and the attribute "value" with data set to "My 504 new comment" is created if not already present, or replaced if it 505 exists. 507 C: a STORE 1 ANNOTATION ("/message/comment" ("value" NIL)) 508 S: a OK Store complete 510 In the above example, the "value" attribute of the entry 511 "/message/comment" is removed. 513 Multiple entries can be set in a single STORE command by listing 514 entry-attribute-value pairs in the list. 516 Example: 517 C: a STORE 1 ANNOTATION ("/message/comment" ("value" 518 "Get tix Tuesday") 519 "/message/subject" ("value" 520 "Wots On")) 521 S: a OK Store complete 523 In the above example, the entries "/message/comment" and 524 "/message/subject" are created (if not already present) and the 525 attribute "value" is created for each entry if not already present, 526 or replaced if they exist. 528 Multiple attributes can be set in a single STORE command by listing 529 multiple attribute-value pairs in the entry list. 531 Example: 532 C: a STORE 1 ANNOTATION ("/message/comment" 533 ("value" "My new comment" 534 "vendor.foobar" "foo's bar")) 535 S: a OK Store complete 537 In the above example, the entry "/message/comment" is created (if 538 not already present) and the attributes "value" and "vendor.foobar" 539 are created if not already present, or replaced if they exist. 541 8.3.1 Conditional Annotation STORE 542 <<>> 544 Should there be a STORE modifier which permits the client to detect 545 and avoid a collision? 547 MODTIME 548 Instructs the server to abort the STORE and return a NO response 549 if any specified entry has a modtime attribute greater than the 550 supplied value. 552 Examples: 553 C: a STORE 1 ANNOTATION MODTIME 19720612140000 554 ("/message/comment" ("value" "Tune a Fish?")) 555 S: a NO Entry modified since specified value 557 In the above example, the client attempts a STORE into the 558 "/message/comment" entry which is conditioned on the entry modtime 559 being 19720612140000 or earlier. 561 C: a STORE 1 ANNOTATION MODTIME 19720612140000 562 ("/message/comment" ("value" "No Comment") 563 "/message/subject" ("value" "The King Is Not a Subject")) 564 S: a NO Entry modified since specified value 566 In the above example, the client attempts a STORE into the 567 "/message/comment" and "/message/subject" entries which is 568 conditioned on neither of the entry modtimes being greater than 569 19720612140000. 571 8.4 ANNOTATION Message Data Item in APPEND 573 ANNOTATION 574 Sets the specified list of entries and attributes in the 575 resulting message. 577 Example: 578 C: a APPEND drafts ANNOTATION ("/message/comment" 579 ("value" "Don't send until we hear from Sally")) {310} 580 S: + Ready for literal data 581 C: MIME-Version: 1.0 582 ... 583 C: 584 S: a OK APPEND completed 586 In the above example, a comment is added to a new message appended 587 to the mailbox. The ellipsis represents the bulk of the message.\ 589 8.5 ANNOTATION-MODTIME Message Data Item in STATUS 591 ANNOTATION-MODTIME 592 Requests that the STATUS command results include the latest 593 modtime of all annotation entries of all messages in the 594 mailbox. 596 Example: 597 C: a STATUS cards (ANNOTATION-MODTIME MESSAGES) 598 S: * STATUS cards (MESSAGES 231 599 ANNOTATION-MODTIME 19991114020700) 600 S: a OK STATUS completed 602 8.6 ANNOTATION Criterion in SEARCH 604 The ANNOTATION criterion for the SEARCH command allows a client to 605 search for a specified string in the value of an annotation entry of 606 a message. 607 ANNOTATION 609 Messages that have annotations with entries matching 610 and attributes matching and the specified string 611 in their values are returned in the SEARCH results. The "*" 612 character can be used in the entry or attribute name fields to match 613 any content in those items. The "%" character can be used in the 614 entry or attribute name fields to match a single level of hierarchy 615 only. 617 Examples: 618 C: a SEARCH ANNOTATION "/message/comment" "value" "IMAP4" 619 S: * SEARCH 2 3 5 7 11 13 17 19 23 620 S: a OK Search complete 622 In the above example, the message numbers of any messages containing 623 the string "IMAP4" in the "value" attribute of the 624 "/message/comment" entry are returned in the search results. 626 C: a SEARCH ANNOTATION "*" "*" "IMAP4" 627 S: * SEARCH 1 2 3 5 8 13 21 34 628 S: a OK Search complete 629 In the above example, the message numbers of any messages containing 630 the string "IMAP4" in any attribute of any entry are returned in the 631 search results. 633 A special case exists when the "modtime" attribute is used as the 634 parameter in the ANNOTATION search criterion. In 635 this case the server matches messages when the corresponding 636 "modtime" value is greater than the value supplied in the ANNOTATION 637 criterion. This allows a client, for example, to find out which 638 messages contain annotations that have changed since the last time 639 it updated its disconnected cache. 641 Example: 642 C: a SEARCH ANNOTATION "*" "modtime" "1999101713283412" 643 S: * SEARCH 1 3 6 10 15 21 28 36 45 55 644 S: a OK Search complete 646 In the above example, the message numbers of any messages whose 647 "modtime" attribute of any entry exceeds the value 648 "1999101713283412" are returned in the search results. 650 8.7 ANNOTATION Key in SORT 652 The ANNOTATION criterion for the SORT command [SORT-EXT] instructs 653 the server to return the message numbers or UIDs of a mailbox, 654 sorted using the values of the specified annotations. The 655 ANNOTATION criterion is available if the server returns both 656 "ANNOTATE" and "SORT" as supported capabilities in the CAPABILITY 657 command response. 658 ANNOTATION 660 Messages are sorted using the values of the 661 attributes in the entries. (The charset argument 662 determines sort order, as specified in the SORT extension 663 description.) 665 Examples: 666 C: a SORT (ANNOTATION "/message/subject" "value") UTF-8 ALL 667 S: * SORT 2 3 4 5 1 11 10 6 7 9 8 668 S: a OK Sort complete 670 In the above example, the message numbers of all messages are 671 returned, sorted according to the "value" attribute of the 672 "/message/subject" entry. 674 Note that the ANNOTATION sort key must include a fully specified 675 entry and attribute -- wildcards are not allowed. 677 8.8 Annotation Modtime Untagged Response 678 <<>> 680 Should there be an untagged Annotation Modtime response? This would 681 be issued by the server during a FETCH or SEARCH command to informs 682 the client of the latest modtime of all entries specified in the 683 FETCH or returned in the SEARCH results. It would also be issued 684 following a group of one or more unsolicited FETCH responses to 685 indicate that the client has received all updates to entries which 686 have modtime values less than or equal to the indicated modtime 687 value. 689 * ANNOTATION-MODTIME 690 Informs the client of the latest modtime used in immediately 691 prior results. 693 Example: 694 C: a SEARCH ANNOTATION "*" "modtime" "1999101713283412" 695 S: * SEARCH 1 3 6 10 15 21 28 36 45 55 696 S: * ANNOTATION-MODTIME 20000624140000 697 S: a OK Search complete 699 8.9 ACL Rights 701 The "r" right, as specified in [ACL-EXT], is required to use 702 annotations in any command other than STORE. 704 The "w" right is needed to use annotations in the STORE command. 706 9 Formal Syntax 708 The following syntax specification uses the Augmented Backus-Naur 709 Form (ABNF) notation as specified in [ABNF]. 711 Non-terminals referenced but not defined below are as defined by 712 [IMAP4]. 714 Except as noted otherwise, all alphabetic characters are case- 715 insensitive. The use of upper or lower case characters to define 716 token strings is for editorial clarity only. Implementations MUST 717 accept these strings in a case-insensitive fashion. 719 append = "APPEND" SP mailbox [SP flag-list] [SP date-time] 720 [SP "ANNOTATION" SP att-annotate] 721 SP literal 722 ; modifies original IMAP4 APPEND command 724 att-annotate = "(" entry-att *(SP entry-att) ")" 726 fetch-att =/ fetch-annotate 727 ; modifies original IMAP4 fetch-att 728 fetch-annotate = "ANNOTATION" SP "(" entries SP attribs ")" 729 fetch-ann-resp = "ANNOTATION" SP "(" entry-att *(SP entry-att) ")" 731 store-att-flags =/ att-annotate 732 ; modifies original IMAP4 STORE command 734 search-key =/ search-annotate 735 ; modifies original IMAP4 search-key 737 search-annotate = "ANNOTATION" SP entry-match SP attrib-match 738 SP value 740 sort-key =/ sort-annotate 741 ; modifies original 742 ; draft-crispin-imapext-sort-xx.txt sort-key 744 sort_annotate = "ANNOTATION" SP entry SP attrib 746 status =/ "ANNOTATION-MODTIME" 747 ; modifies original IMAP4 STATUS command 749 entries = entry-match / 750 "(" entry-match *(SP entry-match) ")" 751 attribs = attrib-match / 752 "(" attrib-match *(SP attrib-match) ")" 753 entry-att = entry SP "(" att-value *(SP att-value) ") 754 att-value = attrib SP value 756 utf8-char = %x01-FF 757 ; any character, excluding NUL 758 atom-slash = any utf8-char except "/" 759 atom-dot = any utf8-char except "." 761 entry = DQUOTE 1*atom-slash *("/" 1*atom-slash) DQUOTE 762 entry-match = DQUOTE 1*entry-match-atom 763 *("/" 1*entry-match-atom) DQUOTE 764 entry-match-atom = 1*(list-wildcards / atom-slash) 765 *(list-wildcards / atom-slash) 767 attrib = DQUOTE 1*atom-dot *("/" 1*atom-dot) DQUOTE 768 attrib-match = DQUOTE 1*attrib-match-atom 769 *("/" 1*attrib-match-atom) DQUOTE 770 attrib-match-atom = 1*(list-wildcards / atom-dot) 771 *(list-wildcards / atom-dot) 773 value = nstring 775 10 IANA Considerations 776 Both entry names and attribute names MUST be specified in a 777 standards track or IESG approved experimental RFC, or fall under the 778 vendor namespace. Vendor names MUST be registered. 780 10.1 Entry and Attribute Registration Template 782 To: iana@iana.org 783 Subject: IMAP Annotate Registration 785 Please register the following IMAP Annotate item: 787 [] Entry [] Attribute 788 [] Vendor [] Open: RFC _______ 790 Name: ______________________________ 792 Description: _______________________ 794 ____________________________________ 796 ____________________________________ 798 Contact person: ____________________ 800 email: ____________________ 802 11 Security Considerations 804 Care must be taken to ensure that annotations whose values are 805 intended to remain private are not stored in mailboxes which are 806 accessible to other users. This includes mailboxes owned by the 807 user by whose ACLs permit access by others as well as any shared 808 mailboxes. 810 12 References 812 [ABNF] Crocker, Overell, "Augmented BNF for Syntax Specifications: 813 ABNF", RFC 2234, Internet Mail Consortium, Demon Internet Ltd, 814 November 1997. 816 [ACAP] Newman, Myers, "ACAP -- Application Configuration Access 817 Protocol", RFC 2244, Innosoft, Netscape, November 1997. 819 [ACL-EXT] Myers, "IMAP4 ACL extension", RFC 2086, Carnegie Mellon, 820 January 1997. 822 [IMAP4] Crispin, "Internet Message Access Protocol - Version 4rev1", 823 RFC 2060, University of Washington, December 1996. 825 [KEYWORDS] Bradner, "Key words for use in RFCs to Indicate 826 Requirement Levels", RFC 2119, Harvard University, March 1997. 828 [SMTP-DSN] Moore, "SMTP Service Extension for Delivery Status 829 Notifications", RFC 1891, University of Tennessee, January 1996. 831 [SORT-EXT] Crispin, "Internet Message Access Protocol -- SORT 832 Extension", work in progress. 833 835 13 Acknowledgments 837 Many thanks to Chris Newman for his detailed comments on the first 838 draft of this document. 840 14 Authors' Addresses 842 Cyrus Daboo 843 Cyrusoft International, Inc. 844 Suite 780, 5001 Baum Blvd. 845 Pittsburgh, PA 15213 846 U.S.A. 848 Phone: +1 412 605 0499 849 Email: daboo@cyrusoft.com 851 Randall Gellens 852 QUALCOMM Incorporated 853 5775 Morehouse Dr. 854 San Diego, CA 92121-2779 855 U.S.A. 857 Phone: +1 858 651 5115 858 Email: randy@qualcomm.com 860 15 Full Copyright Statement 862 Copyright (C) The Internet Society 2000. All Rights Reserved. 864 This document and translations of it may be copied and furnished to 865 others, and derivative works that comment on or otherwise explain it 866 or assist in its implementation may be prepared, copied, published 867 and distributed, in whole or in part, without restriction of any 868 kind, provided that the above copyright notice and this paragraph 869 are included on all such copies and derivative works. However, this 870 document itself may not be modified in any way, such as by removing 871 the copyright notice or references to the Internet Society or other 872 Internet organizations, except as needed for the purpose of 873 developing Internet standards in which case the procedures for 874 copyrights defined in the Internet Standards process must be 875 followed, or as required to translate it into languages other than 876 English. 878 The limited permissions granted above are perpetual and will not be 879 revoked by the Internet Society or its successors or assigns. 881 This document and the information contained herein is provided on an 882 "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING 883 TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING 884 BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION 885 HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF 886 MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.