draft-ietf-imapext-annotate-11.txt   draft-ietf-imapext-annotate-12.txt 
IMAP Extensions Working Group R. Gellens
Internet-Draft QUALCOMM Incorporated IMAP Extensions Working Group C. Daboo
Expires: April 23, 2005 C. Daboo Internet-Draft ISAMET, Inc.
ISAMET, Inc. Expires: August 4, 2005 R. Gellens
October 23, 2004 QUALCOMM Incorporated
February 3, 2005
IMAP ANNOTATE Extension IMAP ANNOTATE Extension
draft-ietf-imapext-annotate-11 draft-ietf-imapext-annotate-12
Status of this Memo Status of this Memo
This document is an Internet-Draft and is subject to all provisions This document is an Internet-Draft and is subject to all provisions
of section 3 of RFC 3667. By submitting this Internet-Draft, each of section 3 of RFC 3667. By submitting this Internet-Draft, each
author represents that any applicable patent or other IPR claims of author represents that any applicable patent or other IPR claims of
which he or she is aware have been or will be disclosed, and any of which he or she is aware have been or will be disclosed, and any of
which he or she become aware will be disclosed, in accordance with which he or she become aware will be disclosed, in accordance with
RFC 3668. RFC 3668.
skipping to change at page 1, line 36 skipping to change at page 1, line 37
and may be updated, replaced, or obsoleted by other documents at any and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress." material or to cite them other than as "work in progress."
The list of current Internet-Drafts can be accessed at The list of current Internet-Drafts can be accessed at
http://www.ietf.org/ietf/1id-abstracts.txt. http://www.ietf.org/ietf/1id-abstracts.txt.
The list of Internet-Draft Shadow Directories can be accessed at The list of Internet-Draft Shadow Directories can be accessed at
http://www.ietf.org/shadow.html. http://www.ietf.org/shadow.html.
This Internet-Draft will expire on April 23, 2005. This Internet-Draft will expire on August 4, 2005.
Copyright Notice Copyright Notice
Copyright (C) The Internet Society (2004). Copyright (C) The Internet Society (2005).
Abstract Abstract
The ANNOTATE extension to the Internet Message Access Protocol The ANNOTATE extension to the Internet Message Access Protocol
permits clients and servers to maintain "metadata" for messages permits clients and servers to maintain "metadata" for messages
stored in an IMAP mailbox. stored in an IMAP mailbox.
Change History (to be removed prior to publication as an RFC) Change History (to be removed prior to publication as an RFC)
Changes from -11 to -12:
1. Fixed raw XML in formal syntax.
2. Fixed double \ in IANA section titles.
3. Fixed APPEND formal syntax.
4. Added annotations to CATENATE extension.
5. Reworded text for unsolicited responses.
6. Fixed formal syntax for fetch responses to extend base spec item.
Changes from -10 to -11: Changes from -10 to -11:
1. Flags are now read-only and exactly match their IMAP 1. Flags are now read-only and exactly match their IMAP
counterparts. counterparts.
2. Added new ACL bits for annotations. 2. Added new ACL bits for annotations.
3. Revise security considerations. 3. Revise security considerations.
4. Fixed some references. 4. Fixed some references.
Changes from -09 to -10: Changes from -09 to -10:
1. Added Content-Language value. 1. Added Content-Language value.
2. Added IANA registrations for entries/attributes in this document. 2. Added IANA registrations for entries/attributes in this document.
skipping to change at page 5, line 24 skipping to change at page 5, line 24
2.4 Access Control . . . . . . . . . . . . . . . . . . . . . . 13 2.4 Access Control . . . . . . . . . . . . . . . . . . . . . . 13
2.5 Access to Standard IMAP Flags and Keywords . . . . . . . . 15 2.5 Access to Standard IMAP Flags and Keywords . . . . . . . . 15
3. IMAP Protocol Changes . . . . . . . . . . . . . . . . . . . 15 3. IMAP Protocol Changes . . . . . . . . . . . . . . . . . . . 15
3.1 General Considerations . . . . . . . . . . . . . . . . . . 15 3.1 General Considerations . . . . . . . . . . . . . . . . . . 15
3.2 Optional parameters with the SELECT/EXAMINE commands . . . 15 3.2 Optional parameters with the SELECT/EXAMINE commands . . . 15
3.3 ANNOTATION Message Data Item in FETCH Command . . . . . . 17 3.3 ANNOTATION Message Data Item in FETCH Command . . . . . . 17
3.4 ANNOTATION Message Data Item in FETCH Response . . . . . . 19 3.4 ANNOTATION Message Data Item in FETCH Response . . . . . . 19
3.5 ANNOTATION Message Data Item in STORE . . . . . . . . . . 20 3.5 ANNOTATION Message Data Item in STORE . . . . . . . . . . 20
3.6 ANNOTATION interaction with COPY . . . . . . . . . . . . . 22 3.6 ANNOTATION interaction with COPY . . . . . . . . . . . . . 22
3.7 ANNOTATION Message Data Item in APPEND . . . . . . . . . . 22 3.7 ANNOTATION Message Data Item in APPEND . . . . . . . . . . 22
3.8 ANNOTATION Criterion in SEARCH . . . . . . . . . . . . . . 22 3.8 ANNOTATION Parameter in CATENATE . . . . . . . . . . . . . 23
3.9 ANNOTATION Key in SORT . . . . . . . . . . . . . . . . . . 23 3.9 ANNOTATION Criterion in SEARCH . . . . . . . . . . . . . . 23
3.10 New ACL Rights . . . . . . . . . . . . . . . . . . . . . 24 3.10 ANNOTATION Key in SORT . . . . . . . . . . . . . . . . . 24
4. Formal Syntax . . . . . . . . . . . . . . . . . . . . . . . 24 3.11 New ACL Rights . . . . . . . . . . . . . . . . . . . . . 25
5. IANA Considerations . . . . . . . . . . . . . . . . . . . . 26 4. Formal Syntax . . . . . . . . . . . . . . . . . . . . . . . 25
5.1 Entry and Attribute Registration Template . . . . . . . . 26 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . 27
5.2 Entry Registrations . . . . . . . . . . . . . . . . . . . 26 5.1 Entry and Attribute Registration Template . . . . . . . . 27
5.2.1 /comment . . . . . . . . . . . . . . . . . . . . . . . 27 5.2 Entry Registrations . . . . . . . . . . . . . . . . . . . 27
5.2.2 /flags/\\answered . . . . . . . . . . . . . . . . . . 27 5.2.1 /comment . . . . . . . . . . . . . . . . . . . . . . . 28
5.2.3 /flags/\\flagged . . . . . . . . . . . . . . . . . . . 28 5.2.2 /flags/\answered . . . . . . . . . . . . . . . . . . . 28
5.2.4 /flags/\\deleted . . . . . . . . . . . . . . . . . . . 28 5.2.3 /flags/\flagged . . . . . . . . . . . . . . . . . . . 29
5.2.5 /flags/\\seen . . . . . . . . . . . . . . . . . . . . 29 5.2.4 /flags/\deleted . . . . . . . . . . . . . . . . . . . 29
5.2.6 /flags/\\draft . . . . . . . . . . . . . . . . . . . . 29 5.2.5 /flags/\seen . . . . . . . . . . . . . . . . . . . . . 30
5.2.7 /flags/\\recent . . . . . . . . . . . . . . . . . . . 30 5.2.6 /flags/\draft . . . . . . . . . . . . . . . . . . . . 30
5.2.8 /flags/$mdnsent . . . . . . . . . . . . . . . . . . . 30 5.2.7 /flags/\recent . . . . . . . . . . . . . . . . . . . . 31
5.2.9 /flags/$redirected . . . . . . . . . . . . . . . . . . 31 5.2.8 /flags/$mdnsent . . . . . . . . . . . . . . . . . . . 31
5.2.10 /flags/$forwarded . . . . . . . . . . . . . . . . . 31 5.2.9 /flags/$redirected . . . . . . . . . . . . . . . . . . 32
5.2.11 /altsubject . . . . . . . . . . . . . . . . . . . . 32 5.2.10 /flags/$forwarded . . . . . . . . . . . . . . . . . 32
5.2.12 /<section-part>/comment . . . . . . . . . . . . . . 32 5.2.11 /altsubject . . . . . . . . . . . . . . . . . . . . 33
5.2.13 /<section-part>/flags/seen . . . . . . . . . . . . . 33 5.2.12 /<section-part>/comment . . . . . . . . . . . . . . 33
5.2.14 /<section-part>/flags/answered . . . . . . . . . . . 33 5.2.13 /<section-part>/flags/seen . . . . . . . . . . . . . 34
5.2.15 /<section-part>/flags/flagged . . . . . . . . . . . 34 5.2.14 /<section-part>/flags/answered . . . . . . . . . . . 34
5.2.16 /<section-part>/flags/forwarded . . . . . . . . . . 34 5.2.15 /<section-part>/flags/flagged . . . . . . . . . . . 35
5.3 Attribute Registrations . . . . . . . . . . . . . . . . . 34 5.2.16 /<section-part>/flags/forwarded . . . . . . . . . . 35
5.3.1 value . . . . . . . . . . . . . . . . . . . . . . . . 35 5.3 Attribute Registrations . . . . . . . . . . . . . . . . . 35
5.3.2 size . . . . . . . . . . . . . . . . . . . . . . . . . 35 5.3.1 value . . . . . . . . . . . . . . . . . . . . . . . . 36
5.3.3 content-type . . . . . . . . . . . . . . . . . . . . . 36 5.3.2 size . . . . . . . . . . . . . . . . . . . . . . . . . 36
5.3.4 content-language . . . . . . . . . . . . . . . . . . . 36 5.3.3 content-type . . . . . . . . . . . . . . . . . . . . . 37
6. Security Considerations . . . . . . . . . . . . . . . . . . 36 5.3.4 content-language . . . . . . . . . . . . . . . . . . . 37
7. References . . . . . . . . . . . . . . . . . . . . . . . . . 37 6. Security Considerations . . . . . . . . . . . . . . . . . . 37
7.1 Normative References . . . . . . . . . . . . . . . . . . . . 37 7. References . . . . . . . . . . . . . . . . . . . . . . . . . 38
7.2 Informative References . . . . . . . . . . . . . . . . . . . 37 7.1 Normative References . . . . . . . . . . . . . . . . . . . . 38
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . 38 7.2 Informative References . . . . . . . . . . . . . . . . . . . 38
A. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . 38 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . 39
Intellectual Property and Copyright Statements . . . . . . . 39 A. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . 39
Intellectual Property and Copyright Statements . . . . . . . 40
1. Introduction and Overview 1. Introduction and Overview
The ANNOTATE extension is present in any IMAP [RFC3501] The ANNOTATE extension is present in any IMAP [RFC3501]
implementation which returns "ANNOTATE" as one of the supported implementation which returns "ANNOTATE" as one of the supported
capabilities in the CAPABILITY response. capabilities in the CAPABILITY response.
The ANNOTATE extension adds a new message data item to the FETCH and The ANNOTATE extension adds a new message data item to the FETCH and
STORE commands, as well as adding SEARCH and SORT keys and an APPEND STORE commands, as well as adding SEARCH and SORT keys and an APPEND
modifier. modifier. It also extends tyhe CATENATE extension with a new
parameter.
This extension makes the following changes to the IMAP protocol: This extension makes the following changes to the IMAP protocol:
a. adds a new ANNOTATION message data item for use in FETCH a. adds a new ANNOTATION message data item for use in FETCH
b. adds a new ANNOTATION message data item for use in STORE b. adds a new ANNOTATION message data item for use in STORE
c. adds a new ANNOTATION search criterion for use in SEARCH c. adds a new ANNOTATION search criterion for use in SEARCH
d. adds a new ANNOTATION sort key for use in SORT extension d. adds a new ANNOTATION sort key for use in SORT extension
e. adds a new ANNOTATION data item for use in APPEND e. adds a new ANNOTATION data item for use in APPEND
f. adds a new requirement on the COPY command f. adds a new ANNOTATION parameter for use in CATENATE
g. adds a extension mechanism for adding parameters to the SELECT/ g. adds a new requirement on the COPY command
h. adds a extension mechanism for adding parameters to the SELECT/
EXAMINE commands and defines the ANNOTATE parameter EXAMINE commands and defines the ANNOTATE parameter
h. adds two new response codes to indicate store failures of i. adds two new response codes to indicate store failures of
annotations. annotations.
i. adds a new untagged response codes for the SELECT or EXAMINE j. adds a new untagged response codes for the SELECT or EXAMINE
commands to indicate the maximum size. commands to indicate the maximum size.
j. adds two new ACL 'bits' for use with the ACL [RFC2086] extension. k. adds two new ACL 'bits' for use with the ACL [ACLUPD] extension.
The data model used for the storage of annotations is based on that The data model used for the storage of annotations is based on that
of the Application Configuration Access Protocol [RFC2244]. Note of the Application Configuration Access Protocol [RFC2244]. Note
that there is no inheritance in annotations. that there is no inheritance in annotations.
Clients MUST NOT use annotations in lieu of equivalent IMAP base
specification facilities. For example, use of a "seen" flag in the
vendor namespace together with ".PEEK" in fetches. Such behaviour
would significantly reduce IMAP interoperability.
If a server supports annotations, then it MUST store all annotation If a server supports annotations, then it MUST store all annotation
data permanently, i.e. there is no concept of 'session only' data permanently, i.e. there is no concept of 'session only'
annotations that would correspond to the behaviour of 'session' flags annotations that would correspond to the behaviour of 'session' flags
as defined in the IMAP base specification. The exception to this is as defined in the IMAP base specification.
IMAP flags (which are accessible directly through annotations) which
may be 'session only' as determined by the FLAGS and PERMANENTFLAGS
responses to a SELECT or EXAMINE command.
This extension also introduces a generalised mechanism for adding This extension also introduces a generalised mechanism for adding
parameters to the SELECT or EXAMINE commands. It is anticipated that parameters to the SELECT or EXAMINE commands. It is anticipated that
other extensions may want to utilise this, so it is not strictly other extensions may want to utilise this, so it is not strictly
dependent on the ANNOTATE extension being present. dependent on the ANNOTATE extension being present.
In order to provide optimum support for a disconnected client (one In order to provide optimum support for a disconnected client (one
that needs to synchronise annotations for use when offline), servers that needs to synchronise annotations for use when offline), servers
SHOULD also support the Conditional STORE [CONDSTORE] extension. SHOULD also support the Conditional STORE [CONDSTORE] extension.
skipping to change at page 11, line 17 skipping to change at page 11, line 15
specific body part of a message. All sub-entries are maintained specific body part of a message. All sub-entries are maintained
entirely by the client. There is no implicit change to any flag entirely by the client. There is no implicit change to any flag
by the server. by the server.
/<section-part>/flags/seen /<section-part>/flags/seen
/<section-part>/flags/answered /<section-part>/flags/answered
/<section-part>/flags/flagged /<section-part>/flags/flagged
/<section-part>/flags/forwarded /<section-part>/flags/forwarded
Defines flags for a specific body part of a message. The "value" Defines flags for a specific body part of a message. The "value"
attribute of these entries must be either "1", "0" or NIL. attribute of these entries must be either "1" or "0".
/<section-part>/vendor/<vendor-token> /<section-part>/vendor/<vendor-token>
Defines the top-level of entries associated with a specific body Defines the top-level of entries associated with a specific body
part of a message as created by a particular product of some part of a message as created by a particular product of some
vendor. This entry can be used by vendors to provide client vendor. This entry can be used by vendors to provide client
specific attributes. The vendor-token MUST be registered with specific attributes. The vendor-token MUST be registered with
IANA. IANA.
2.2.2 Attribute Names 2.2.2 Attribute Names
skipping to change at page 12, line 20 skipping to change at page 12, line 18
vendor.<vendor-token> vendor.<vendor-token>
Defines an attribute associated with a particular product of some Defines an attribute associated with a particular product of some
vendor. This attribute can be used by vendors to provide client vendor. This attribute can be used by vendors to provide client
specific attributes. The vendor-token MUST be registered with specific attributes. The vendor-token MUST be registered with
IANA, using the [RFC2244] vendor subtree registry. IANA, using the [RFC2244] vendor subtree registry.
2.3 Private versus Shared 2.3 Private versus Shared
Some IMAP mailboxes are private, accessible only to the owning user. Some IMAP mailboxes are private, accessible only to the owning user.
Other mailboxes are not, either because the owner has set an ACL Other mailboxes are not, either because the owner has set an ACL
[RFC2086] which permits access by other users, or because it is a [ACLUPD] which permits access by other users, or because it is a
shared mailbox. shared mailbox.
This raises the issue of shared versus private annotations. This raises the issue of shared versus private annotations.
If all annotations are private, it is impossible to set annotations If all annotations are private, it is impossible to set annotations
in a shared or otherwise non-private mailbox that are visible to in a shared or otherwise non-private mailbox that are visible to
other users. This eliminates what could be a useful aspect of other users. This eliminates what could be a useful aspect of
annotations in a shared environment. An example of such use is a annotations in a shared environment. An example of such use is a
shared IMAP folder containing bug reports. Engineers may want to use shared IMAP folder containing bug reports. Engineers may want to use
annotations to add information to existing messages, indicate annotations to add information to existing messages, indicate
skipping to change at page 13, line 10 skipping to change at page 13, line 9
This document proposes two standard suffixes for all attributes: This document proposes two standard suffixes for all attributes:
".shared" and ".priv". A search, fetch, or sort which specifies ".shared" and ".priv". A search, fetch, or sort which specifies
neither uses both. Store operations MUST explicitly use .priv or neither uses both. Store operations MUST explicitly use .priv or
.shared suffixes. .shared suffixes.
2.4 Access Control 2.4 Access Control
A user needs to have appropriate rights in order to read or write A user needs to have appropriate rights in order to read or write
.priv or .shared annotation values. How those rights are calculated .priv or .shared annotation values. How those rights are calculated
depends on whether the ACL [RFC2086] extension is present or not. If depends on whether the ACL [ACLUPD] extension is present or not. If
a client attempts to store or fetch an annotation to which they do a client attempts to store or fetch an annotation to which they do
not have the appropriate rights, the server MUST respond with a NO not have the appropriate rights, the server MUST respond with a NO
response. response.
When the ACL extension is not present, access to annotation values is When the ACL extension is not present, access to annotation values is
governed by the nature of the selected state. In particular whether governed by the nature of the selected state. In particular whether
the mailbox was SELECT'ed or EXAMINE'd in READ-ONLY or READ-WRITE the mailbox was SELECT'ed or EXAMINE'd in READ-ONLY or READ-WRITE
mode. mode.
When the ACL extension is present, the server MUST recognise two new When the ACL extension is present, the server MUST recognise two new
skipping to change at page 17, line 11 skipping to change at page 17, line 11
followed by a quoted string. followed by a quoted string.
Example: Example:
C: a SELECT INBOX (BLURDYBLOOP) C: a SELECT INBOX (BLURDYBLOOP)
S: a NO Unknown parameter in SELECT command S: a NO Unknown parameter in SELECT command
In the above example, a parameter not supported by the server is In the above example, a parameter not supported by the server is
incorrectly used. incorrectly used.
The ANNOTATE extension defines a single optional select parameter The ANNOTATE extension defines a single optional SELECT parameter
"ANNOTATE", which is used to turn on unsolicited responses for "ANNOTATE", which is used to turn on unsolicited responses for
annotations as described in Section 3.4. This option al parameter is annotations as described in Section 3.4. This optional parameter
results in a per-mailbox state change, i.e. it must be used in each results in a per-mailbox state change, i.e. it must be used in each
SELECT/EXAMINE command in order to be effective, irrespective of SELECT/EXAMINE command in order to be effective, irrespective of
whether it was used in a previous SELECT/EXAMINE during the same whether it was used in a previous SELECT/EXAMINE during the same
session. session.
3.3 ANNOTATION Message Data Item in FETCH Command 3.3 ANNOTATION Message Data Item in FETCH Command
This extension adds an ANNOTATION message data item to the FETCH This extension adds an ANNOTATION message data item to the FETCH
command. This allows clients to retrieve annotations for a range of command. This allows clients to retrieve annotations for a range of
messages in the currently selected mailbox. messages in the currently selected mailbox.
skipping to change at page 20, line 20 skipping to change at page 20, line 20
"value.shared" NIL "value.shared" NIL
"size.priv" "10" "size.priv" "10"
"size.shared" "0"))) "size.shared" "0")))
S: a OK Fetch complete S: a OK Fetch complete
In the above example, a single entry with two attribute-value In the above example, a single entry with two attribute-value
pairs is returned by the server. Since the client did not specify pairs is returned by the server. Since the client did not specify
a ".shared" or ".priv" suffix, both are returned. Only the a ".shared" or ".priv" suffix, both are returned. Only the
private attributes have values; the shared attributes are NIL. private attributes have values; the shared attributes are NIL.
Servers MUST NOT include ANNOTATION data in unsolicited responses
unless the client used the ANNOTATE select parameter when it issued
the last SELECT or EXAMINE command. This restriction avoids sending
ANNOTATION data to a client unless the client explicitly asks for it.
Servers SHOULD send ANNOTATION message data items in unsolicited Servers SHOULD send ANNOTATION message data items in unsolicited
FETCH responses if an annotation entry is changed by a third-party, FETCH responses if an annotation entry is changed by a third-party,
and the ANNOTATE select parameter was used. This allows servers to and the ANNOTATE select parameter was used. This allows servers to
keep clients updated with changes to annotations by other clients. keep clients updated with changes to annotations by other clients.
Unsolicited ANNOTATION responses MUST NOT include ANNOTATION data
values - only the entry name of the ANNOTATION that has changed.
This restriction avoids sending ANNOTATION data values (which may be
large) to a client unless the client explicitly asks for the value.
Example:
C: a STORE 1 +FLAGS (\Seen)
S: * 1 FETCH (FLAGS (\Seen))
ANNOTATION ("/comment"))
S: a OK STORE complete
In the above example, an unsolicited ANNOTATION response is
returned during a STORE command. The unsolicited response
contains only the entry name of the annotation that changed, and
not its value.
3.5 ANNOTATION Message Data Item in STORE 3.5 ANNOTATION Message Data Item in STORE
ANNOTATION <parenthesised entry-attribute-value list> ANNOTATION <parenthesised entry-attribute-value list>
Sets the specified list of entries by adding or replacing the Sets the specified list of entries by adding or replacing the
specified attributes with the values provided. Clients can use specified attributes with the values provided. Clients can use
NIL for values of attributes it wants to remove from entries. NIL for values of attributes it wants to remove from entries.
The ANNOTATION message data item used with the STORE command has an The ANNOTATION message data item used with the STORE command has an
implicit ".SILENT" behaviour. This means the server does not implicit ".SILENT" behaviour. This means the server does not
skipping to change at page 22, line 40 skipping to change at page 23, line 4
item can also be used with the multi-append [RFC3502] extension that item can also be used with the multi-append [RFC3502] extension that
allows multiple messages to be appended via a single APPEND command. allows multiple messages to be appended via a single APPEND command.
Example: Example:
C: a APPEND drafts ANNOTATION ("/comment" C: a APPEND drafts ANNOTATION ("/comment"
("value.priv" "Don't send until we hear from Sally")) {310} ("value.priv" "Don't send until we hear from Sally")) {310}
S: + Ready for literal data S: + Ready for literal data
C: MIME-Version: 1.0 C: MIME-Version: 1.0
... ...
C: C:
S: a OK APPEND completed S: a OK APPEND completed
In the above example, a comment with a private value is added to a In the above example, a comment with a private value is added to a
new message appended to the mailbox. The ellipsis represents the new message appended to the mailbox. The ellipsis represents the
bulk of the message. bulk of the message.
3.8 ANNOTATION Criterion in SEARCH 3.8 ANNOTATION Parameter in CATENATE
ANNOTATION <parenthesised entry-attribute-value list>
Sets the specified list of entries and attributes in the resulting
message.
The CATENATE [CATENATE] extension defines a new command similar to
the APPEND command. When the CATENATE extension is present on a
server that also supports the ANNOTATE extension, the CATENATE
command MUST allow annotations to be added to the message being
'catenated' via the addition of a new parameter item in the command.
Example:
C: a CATENATE drafts ANNOTATION ("/comment"
("value.priv" "Don't send until we hear from Sally"))
TEXT {310}
S: + Ready for literal data
C: MIME-Version: 1.0
...
C:
S: a OK CATENATE completed
In the above example, a comment with a private value is added to a
new message 'catenated' to the mailbox. The ellipsis represents
the bulk of the message.
3.9 ANNOTATION Criterion in SEARCH
ANNOTATION <entry-name> <attribute-name> <value> ANNOTATION <entry-name> <attribute-name> <value>
The ANNOTATION criterion for the SEARCH command allows a client to The ANNOTATION criterion for the SEARCH command allows a client to
search for a specified string in the value of an annotation entry of search for a specified string in the value of an annotation entry of
a message. a message.
Messages that have annotations with entries matching <entry-name> and Messages that have annotations with entries matching <entry-name> and
attributes matching <attribute-name> and the specified string <value> attributes matching <attribute-name> and the specified string <value>
in their values are returned in the SEARCH results. The "*" in their values are returned in the SEARCH results. The "*"
skipping to change at page 23, line 36 skipping to change at page 24, line 28
Example: Example:
C: a SEARCH ANNOTATION "*" "*" "IMAP4" C: a SEARCH ANNOTATION "*" "*" "IMAP4"
S: * SEARCH 1 2 3 5 8 13 21 34 S: * SEARCH 1 2 3 5 8 13 21 34
S: a OK Search complete S: a OK Search complete
In the above example, the message numbers of any messages In the above example, the message numbers of any messages
containing the string "IMAP4" in any attribute (public or private) containing the string "IMAP4" in any attribute (public or private)
of any entry are returned in the search results. of any entry are returned in the search results.
3.9 ANNOTATION Key in SORT 3.10 ANNOTATION Key in SORT
ANNOTATION <entry-name> <attribute-name> ANNOTATION <entry-name> <attribute-name>
The ANNOTATION criterion for the SORT command [SORT] instructs the The ANNOTATION criterion for the SORT command [SORT] instructs the
server to return the message numbers or UIDs of a mailbox, sorted server to return the message numbers or UIDs of a mailbox, sorted
using the values of the specified annotations. The ANNOTATION using the values of the specified annotations. The ANNOTATION
criterion is available if the server returns both "ANNOTATE" and criterion is available if the server returns both "ANNOTATE" and
"SORT" as supported capabilities in the CAPABILITY command response. "SORT" as supported capabilities in the CAPABILITY command response.
Messages are sorted using the values of the <attribute-name> Messages are sorted using the values of the <attribute-name>
skipping to change at page 24, line 16 skipping to change at page 25, line 8
S: * SORT 2 3 4 5 1 11 10 6 7 9 8 S: * SORT 2 3 4 5 1 11 10 6 7 9 8
S: a OK Sort complete S: a OK Sort complete
In the above example, the message numbers of all messages are In the above example, the message numbers of all messages are
returned, sorted according to the shared "value" attribute of the returned, sorted according to the shared "value" attribute of the
"/altsubject" entry. "/altsubject" entry.
Note that the ANNOTATION sort key must include a fully specified Note that the ANNOTATION sort key must include a fully specified
entry and attribute -- wildcards are not allowed. entry and attribute -- wildcards are not allowed.
3.10 New ACL Rights 3.11 New ACL Rights
As discussed in Section 2.4 this extension adds new 'm' and 'n' As discussed in Section 2.4 this extension adds new 'm' and 'n'
rights to the list of rights provided by the ACL [RFC2086] extension. rights to the list of rights provided by the ACL [ACLUPD] extension.
4. Formal Syntax 4. Formal Syntax
The following syntax specification uses the Augmented Backus-Naur The following syntax specification uses the Augmented Backus-Naur
Form (ABNF) notation as specified in [RFC2234]. Form (ABNF) notation as specified in [RFC2234].
Non-terminals referenced but not defined below are as defined by Non-terminals referenced but not defined below are as defined by
[RFC3501]. [RFC3501].
Except as noted otherwise, all alphabetic characters are Except as noted otherwise, all alphabetic characters are
case-insensitive. The use of upper or lower case characters to case-insensitive. The use of upper or lower case characters to
define token strings is for editorial clarity only. Implementations define token strings is for editorial clarity only. Implementations
MUST accept these strings in a case-insensitive fashion. MUST accept these strings in a case-insensitive fashion.
annotate-param = "ANNOTATE" annotate-param = "ANNOTATE"
; defines the select parameter used with ; defines the select parameter used with
; ANNOTATE extension ; ANNOTATE extension
append = "APPEND" SP mailbox [SP flag-list] [SP date-time] append = "APPEND" SP mailbox [SP flag-list] [SP date-time]
[SP "ANNOTATION" SP att-annotate] SP literal [SP att-annotate] SP literal
; modifies original IMAP APPEND command ; modifies original IMAP APPEND command
append-message = [SP flag-list] [SP date-time] append-message = [SP flag-list] [SP date-time]
[SP "ANNOTATION" SP att-annotate] SP literal [SP att-annotate] SP literal
; modifies [MULTIAPPEND] extension behaviour ; modifies [MULTIAPPEND] extension behaviour
att-annotate = "ANNOTATION" SP "(" entry-att *(SP entry-att) ")" att-annotate = "ANNOTATION" SP "(" entry-att *(SP entry-att) ")"
att-match = string att-match = string
; dot-separated attribute name ; dot-separated attribute name
; MAY contain "*" or "%" for use as wildcards ; MAY contain "*" or "%" for use as wildcards
att-value = attrib SP value att-value = attrib SP value
attrib = string attrib = string
; dot-separated attribute name ; dot-separated attribute name
; MUST NOT contain "*" or "%" ; MUST NOT contain "*" or "%"
attribs = att-match / attribs = att-match /
"(" att-match *(SP att-match) ")" "(" att-match *(SP att-match) ")"
entries = entry-match / entries = entry-match /
"(" entry-match *(SP entry-match) ")" "(" entry-match *(SP entry-match) ")"
entry = string entry = string
; slash-separated path to entry ; slash-separated path to entry
; MUST NOT contain "*" or "%" ; MUST NOT contain "*" or "%"
entry-att = entry SP "(" att-value *(SP att-value) ")" entry-att = entry SP "(" att-value *(SP att-value) ")"
entry-match = string entry-match = string
skipping to change at page 25, line 28 skipping to change at page 26, line 21
entry-att = entry SP "(" att-value *(SP att-value) ")" entry-att = entry SP "(" att-value *(SP att-value) ")"
entry-match = string entry-match = string
; slash-separated path to entry ; slash-separated path to entry
; MAY contain "*" or "%" for use as wildcards ; MAY contain "*" or "%" for use as wildcards
examine =/ *(SP "(" select-param *(SP select-param) ")" examine =/ *(SP "(" select-param *(SP select-param) ")"
; modifies the original IMAP examine command to ; modifies the original IMAP examine command to
; accept optional parameters ; accept optional parameters
fetch-ann-resp = "ANNOTATION" SP "(" entry-att *(SP entry-att) ")"
fetch-att =/ "ANNOTATION" SP "(" entries SP attribs ")" fetch-att =/ "ANNOTATION" SP "(" entries SP attribs ")"
; modifies original IMAP fetch-att ; modifies original IMAP fetch-att
msg-att-dynamic =/ "ANNOTATION" SP
( "(" entry-att *(SP entry-att) ")" /
"(" entry *(SP entry) ")" )
; extends FETCH response with annotation data
parameter =/ att-annotate
; modifies original IMAP CATENATE formal syntax
; to include annotations
resp-text-code =/ "ANNOTATE" SP "TOOBIG" / resp-text-code =/ "ANNOTATE" SP "TOOBIG" /
"ANNOTATE" SP "TOOMANY" / "ANNOTATE" SP "TOOMANY" /
"ANNOTATESIZE" SP (number / "NIL") "ANNOTATESIZE" SP (number / "NIL")
; new response codes ; new response codes
search-key =/ "ANNOTATION" SP entry-match SP att-match search-key =/ "ANNOTATION" SP entry-match SP att-match
SP value SP value
; modifies original IMAP search-key ; modifies original IMAP search-key
select =/ *(SP "(" select-param *(SP select-param) ")" select =/ *(SP "(" select-param *(SP select-param) ")"
; modifies the original IMAP select command to ; modifies the original IMAP select command to
; accept optional parameters ; accept optional parameters
select-param = astring / "(" astring SP astring *(SP astring) ")" select-param = astring / "(" astring SP astring *(SP astring) ")"
; parameters to SELECT may contain one or ; parameters to SELECT may contain one or
; more atoms or strings - multiple items ; more atoms or strings - multiple items
; are always parenthesised ; are always parenthesised
sort-key =/ "ANNOTATION" SP entry SP attrib sort-key =/ "ANNOTATION" SP entry SP attrib
; modifies original sort-key <xref target='SORT' /> ; modifies original sort-key
store-att-flags =/ att-annotate store-att-flags =/ att-annotate
; modifies original IMAP STORE command ; modifies original IMAP STORE command
value = nstring value = nstring
5. IANA Considerations 5. IANA Considerations
Both entry names and attribute names MUST be specified in a standards Both entry names and attribute names MUST be specified in a standards
track or IESG approved experimental RFC, or fall under the vendor track or IESG approved experimental RFC, or fall under the vendor
skipping to change at page 27, line 22 skipping to change at page 28, line 22
[X] Entry [] Attribute [X] Entry [] Attribute
Name: /comment Name: /comment
Description: Defined in IMAP ANNOTATE extension document. Description: Defined in IMAP ANNOTATE extension document.
Contact person: Cyrus Daboo Contact person: Cyrus Daboo
email: daboo@isamet.com email: daboo@isamet.com
5.2.2 /flags/\\answered 5.2.2 /flags/\answered
To: iana@iana.org To: iana@iana.org
Subject: IMAP Annotate Registration Subject: IMAP Annotate Registration
Please register the following IMAP Annotate item: Please register the following IMAP Annotate item:
[X] Entry [] Attribute [X] Entry [] Attribute
Name: /flags/\answered Name: /flags/\answered
Description: Defined in IMAP ANNOTATE extension document. Description: Defined in IMAP ANNOTATE extension document.
Contact person: Cyrus Daboo Contact person: Cyrus Daboo
email: daboo@isamet.com email: daboo@isamet.com
5.2.3 /flags/\\flagged 5.2.3 /flags/\flagged
To: iana@iana.org To: iana@iana.org
Subject: IMAP Annotate Registration Subject: IMAP Annotate Registration
Please register the following IMAP Annotate item: Please register the following IMAP Annotate item:
[X] Entry [] Attribute [X] Entry [] Attribute
Name: /flags/\flagged Name: /flags/\flagged
Description: Defined in IMAP ANNOTATE extension document. Description: Defined in IMAP ANNOTATE extension document.
Contact person: Cyrus Daboo Contact person: Cyrus Daboo
email: daboo@isamet.com email: daboo@isamet.com
5.2.4 /flags/\\deleted 5.2.4 /flags/\deleted
To: iana@iana.org To: iana@iana.org
Subject: IMAP Annotate Registration Subject: IMAP Annotate Registration
Please register the following IMAP Annotate item: Please register the following IMAP Annotate item:
[X] Entry [] Attribute [X] Entry [] Attribute
Name: /flags/\deleted Name: /flags/\deleted
Description: Defined in IMAP ANNOTATE extension document. Description: Defined in IMAP ANNOTATE extension document.
Contact person: Cyrus Daboo Contact person: Cyrus Daboo
email: daboo@isamet.com email: daboo@isamet.com
5.2.5 /flags/\\seen 5.2.5 /flags/\seen
To: iana@iana.org To: iana@iana.org
Subject: IMAP Annotate Registration Subject: IMAP Annotate Registration
Please register the following IMAP Annotate item: Please register the following IMAP Annotate item:
[X] Entry [] Attribute [X] Entry [] Attribute
Name: /flags/\seen Name: /flags/\seen
Description: Defined in IMAP ANNOTATE extension document. Description: Defined in IMAP ANNOTATE extension document.
Contact person: Cyrus Daboo Contact person: Cyrus Daboo
email: daboo@isamet.com email: daboo@isamet.com
5.2.6 /flags/\\draft 5.2.6 /flags/\draft
To: iana@iana.org To: iana@iana.org
Subject: IMAP Annotate Registration Subject: IMAP Annotate Registration
Please register the following IMAP Annotate item: Please register the following IMAP Annotate item:
[X] Entry [] Attribute [X] Entry [] Attribute
Name: /flags/\draft Name: /flags/\draft
Description: Defined in IMAP ANNOTATE extension document. Description: Defined in IMAP ANNOTATE extension document.
Contact person: Cyrus Daboo Contact person: Cyrus Daboo
email: daboo@isamet.com email: daboo@isamet.com
5.2.7 /flags/\\recent 5.2.7 /flags/\recent
To: iana@iana.org To: iana@iana.org
Subject: IMAP Annotate Registration Subject: IMAP Annotate Registration
Please register the following IMAP Annotate item: Please register the following IMAP Annotate item:
[X] Entry [] Attribute [X] Entry [] Attribute
Name: /flags/\recent Name: /flags/\recent
skipping to change at page 37, line 9 skipping to change at page 38, line 9
accessible to other users. accessible to other users.
Excluding the above issues the ANNOTATE extension does not raise any Excluding the above issues the ANNOTATE extension does not raise any
security considerations that are not present in the base IMAP security considerations that are not present in the base IMAP
protocol, and these issues are discussed in [RFC3501]. protocol, and these issues are discussed in [RFC3501].
7. References 7. References
7.1 Normative References 7.1 Normative References
[ACLUPD] Melnikov, A., "IMAP4 ACL extension",
draft-ietf-imapext-2086upd-02.txt, December 2004.
[CATENATE]
Resnick, P., "Internet Message Access Protocol (IMAP)
CATENATE Extension", draft-ietf-lemonade-catenate-03.txt,
December 2004.
[RFC1891] Moore, K., "SMTP Service Extension for Delivery Status [RFC1891] Moore, K., "SMTP Service Extension for Delivery Status
Notifications", RFC 1891, January 1996. Notifications", RFC 1891, January 1996.
[RFC2046] Freed, N. and N. Borenstein, "Multipurpose Internet Mail [RFC2046] Freed, N. and N. Borenstein, "Multipurpose Internet Mail
Extensions (MIME) Part Two: Media Types", RFC 2046, Extensions (MIME) Part Two: Media Types", RFC 2046,
November 1996. November 1996.
[RFC2086] Myers, J., "IMAP4 ACL extension", RFC 2086, January 1997.
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119, March 1997. Requirement Levels", BCP 14, RFC 2119, March 1997.
[RFC2234] Crocker, D. and P. Overell, "Augmented BNF for Syntax [RFC2234] Crocker, D. and P. Overell, "Augmented BNF for Syntax
Specifications: ABNF", RFC 2234, November 1997. Specifications: ABNF", RFC 2234, November 1997.
[RFC2244] Newman, C. and J. Myers, "ACAP -- Application [RFC2244] Newman, C. and J. Myers, "ACAP -- Application
Configuration Access Protocol", RFC 2244, November 1997. Configuration Access Protocol", RFC 2244, November 1997.
[RFC3282] Alvestrand, H., "Content Language Headers", RFC 3282, May [RFC3282] Alvestrand, H., "Content Language Headers", RFC 3282, May
skipping to change at page 38, line 7 skipping to change at page 39, line 10
7.2 Informative References 7.2 Informative References
[CONDSTORE] [CONDSTORE]
Melnikov, A. and S. Hole, "IMAP Extension for Conditional Melnikov, A. and S. Hole, "IMAP Extension for Conditional
STORE operation", draft-ietf-imapext-condstore-05.txt, STORE operation", draft-ietf-imapext-condstore-05.txt,
November 2003. November 2003.
Authors' Addresses Authors' Addresses
Randall Gellens
QUALCOMM Incorporated
5775 Morehouse Dr.
San Diego, CA 92121-2779
US
EMail: randy@qualcomm.com
Cyrus Daboo Cyrus Daboo
ISAMET, Inc. ISAMET, Inc.
5001 Baum Blvd. 5001 Baum Blvd.
Suite 650 Suite 650
Pittsburgh, PA 15213 Pittsburgh, PA 15213
US US
EMail: daboo@isamet.com EMail: daboo@isamet.com
Randall Gellens
QUALCOMM Incorporated
5775 Morehouse Dr.
San Diego, CA 92121-2779
US
EMail: randy@qualcomm.com
Appendix A. Acknowledgments Appendix A. Acknowledgments
Many thanks to Chris Newman for his detailed comments on the first Many thanks to Chris Newman for his detailed comments on the first
draft of this document, and to the participants at the ACAP working draft of this document, and to the participants at the ACAP working
dinner in Pittsburgh. dinner in Pittsburgh.
Intellectual Property Statement Intellectual Property Statement
The IETF takes no position regarding the validity or scope of any The IETF takes no position regarding the validity or scope of any
Intellectual Property Rights or other rights that might be claimed to Intellectual Property Rights or other rights that might be claimed to
skipping to change at page 39, line 41 skipping to change at page 40, line 41
This document and the information contained herein are provided on an This document and the information contained herein are provided on an
"AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS
OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY AND THE INTERNET OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY AND THE INTERNET
ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS OR IMPLIED, ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS OR IMPLIED,
INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE
INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED
WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
Copyright Statement Copyright Statement
Copyright (C) The Internet Society (2004). This document is subject Copyright (C) The Internet Society (2005). This document is subject
to the rights, licenses and restrictions contained in BCP 78, and to the rights, licenses and restrictions contained in BCP 78, and
except as set forth therein, the authors retain all their rights. except as set forth therein, the authors retain all their rights.
Acknowledgment Acknowledgment
Funding for the RFC Editor function is currently provided by the Funding for the RFC Editor function is currently provided by the
Internet Society. Internet Society.
 End of changes. 

This html diff was produced by rfcdiff 1.23, available from http://www.levkowetz.com/ietf/tools/rfcdiff/