WDIFF

draft-daboo-imap-annotatemore-05.txt --> draft-daboo-imap-annotatemore-06.txt

Internet-Draft Cyrusoft International, ISAMET, Inc.
Expires: October 18, 2004 April 19, 1, 2005 October 2004

IMAP ANNOTATEMORE Extension
draft-daboo-imap-annotatemore-05
draft-daboo-imap-annotatemore-06

Status of this Memo

This document is an Internet-Draft and is in full conformance with subject to all provisions
of Section 10 section 3 of RFC 3667. By submitting this Internet-Draft, each
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 RFC2026.
which he or she become aware will be disclosed, in accordance with
RFC 3668.

Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF), its areas, and its working groups. Note that
other groups may also distribute working documents as
Internet-Drafts.

Internet-Drafts are draft documents valid for a maximum of six months
and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress."

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
http://www.ietf.org/shadow.html.

This Internet-Draft will expire on October 18, 2004. April 1, 2005.

Abstract

The ANNOTATEMORE extension to the Internet Message Access Protocol
permits clients and servers to maintain "metadata" on IMAP4 IMAP servers.
It is possible to store data on a per-mailbox basis or on the server
as a whole.

Change History (to be removed prior to publication as an RFC)

Changes from -05 to -06:

Daboo Expires April 1, 2005 [Page 1]
Internet-Draft IMAP ANNOTATEMORE Extension October 2004

1. Removed 'modifiedsince' attribute as there is currently no use
for it.
2. Added content-language attribute.
3. Changed access to allow .priv and .shared on any mailbox returned
by LIST/LSUB.
4. Added IANA registrations for items defined in this document.
5. Added latest IPR statement.
6. Updated references.

Changes from -04 to -05:
1. Fix for valid IMAP state of commands.
2. Fix formatting, ID nits etc.

Changes from -03 to -04:

Daboo Expires October 18, 2004 [Page 1]

Internet-Draft IMAP ANNOTATEMORE Extension April 2004
1. Allow retrieval of shared annotations for READ-ONLY mailbox.
2. Clarification of annotation loss on implicit removal of \Noselect
mailboxes.
3. Now requires roll-back of all changes to matching mailboxes if
there is a partial failure in SETANNOTATION.

Changes from -02 to -03:
1. Reworked entry naming scheme to split out mailbox name and use
empty string for server items.

Changes from -01 to -02:
1. SETANNOTATION lists use (..).
2. Explicitly state behaviour of unsolicited responses.
3. Adding SHOULD behaviour for rename/delete of mailboxes.
4. Added statement about supporting annotations on \Noselect
mailboxes.
5. Cleaned up formal syntax to use IMAP string type for entry and
attributes, with requirements on how the string is formatted.
6. Use of ACAP vendor subtree registry for vendor tokens.

Changes from -00 to -01:
1. Multiple entry-att responses are now simply delimited by spaces
in line with ANNOTATE spec. Adjusted examples to match.
2. Fixed entry-list formal syntax item to account for unsolicited
parenthesised list of entries.
3. Removed setentries formal syntax item for simplicity since its
only used once.
4. Removed reference to 'message annotation' in section 5.1.
5. Changed formal syntax to restrict top level entries to /server
and /mailbox/{...} only. Re-arranged entry names section to
account for this change.
6. Added comment and example for ANNOTATION response to allow
servers to return separate responses for each entry if desired.

Daboo Expires October 18, 2004 April 1, 2005 [Page 2]
Internet-Draft IMAP ANNOTATEMORE Extension April October 2004

Table of Contents

1. Introduction and Overview . . . . . . . . . . . . . . . . . . 4
2. Data Model . . . . . . . . . . . . . . . . . . . . . . . . . . 4
2.1 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . 4
2.2 Namespace of entries and attributes . . . . . . . . . . . . 5
2.2.1 Entry Names . . . . . . . . . . . . . . . . . . . . . . . . 5
2.2.2 Attribute Names . . . . . . . . . . . . . . . . . . . . . . 6
2.3 Private versus Shared and Access Control . . . . . . . . . . 7
3. IMAP Protocol Changes . . . . . . . . . . . . . . . . . . . . 8
3.1 General Considerations . . . . . . . . . . . . . . . . . . . 8
3.2 GETANNOTATION Command . . . . . . . . . . . . . . . . . . . 8
3.3 SETANNOTATION Command . . . . . . . . . . . . . . . . . . . 10
3.4 ANNOTATION Response . . . . . . . . . . . . . . . . . . . . 12
3.4.1 ANNOTATION response with attributes and values . . . . . . . 13
3.4.2 Unsolicited ANNOTATION response without attributes
and values . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
4. Formal Syntax . . . . . . . . . . . . . . . . . . . . . . . . 15
5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 16
5.1 Entry and Attribute Registration Template . . . . . . . . . 17
6. Security Considerations
5.2 Server Entry Registrations . . . . . . . . . . . . . . . . 17
5.2.1 /comment . . . 17
Normative References . . . . . . . . . . . . . . . . . . . . 17
Informative References
5.2.2 /motd . . . . . . . . . . . . . . . . . . . . . . . . 18
Author's Address
5.2.3 /admin . . . . . . . . . . . . . . . . . . . . . . . . 18
A. Acknowledgments
5.3 Mailbox Entry Registrations . . . . . . . . . . . . . . . 18
5.3.1 /comment . . . . . . . . . . . . . . . . 18
Intellectual Property and Copyright Statements . . . . . . . 19

Daboo Expires October 18, 2004 [Page 3]

Internet-Draft IMAP ANNOTATEMORE Extension April 2004

1. Introduction and Overview

The ANNOTATEMORE extension is present in any IMAP4 [RFC3501]
implementation which returns "ANNOTATEMORE" as one of the supported
capabilities in the CAPABILITY command response.

The goal of ANNOTATEMORE is to provide a means for clients to store
and retrieve "metadata" on an IMAP4 server. The metadata can be
associated with specific mailboxes or the server as a whole.
5.3.2 /sort . . . . . . . . . . . . . . . . . . . . . . . . 19
5.3.3 /thread . . . . . . . . . . . . . . . . . . . . . . . 20
5.3.4 /check . . . . . . . . . . . . . . . . . . . . . . . . 20
5.3.5 /checkperiod . . . . . . . . . . . . . . . . . . . . . 21
5.4 Attribute Registrations . . . . . . . . . . . . . . . . . 21
5.4.1 value . . . . . . . . . . . . . . . . . . . . . . . . 21
5.4.2 size . . . . . . . . . . . . . . . . . . . . . . . . . 22
5.4.3 content-type . . . . . . . . . . . . . . . . . . . . . 22
5.4.4 content-language . . . . . . . . . . . . . . . . . . . 23
6. Security Considerations . . . . . . . . . . . . . . . . . . . 23
7. References . . . . . . . . . . . . . . . . . . . . . . . . . . 23
7.1 Normative References . . . . . . . . . . . . . . . . . . . . 23
7.2 Informative References . . . . . . . . . . . . . . . . . . . 24
Author's Address . . . . . . . . . . . . . . . . . . . . . . . 24
A. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 24
Intellectual Property and Copyright Statements . . . . . . . . 25

Daboo Expires April 1, 2005 [Page 3]
Internet-Draft IMAP ANNOTATEMORE Extension October 2004

1. Introduction and Overview

The ANNOTATEMORE extension is present in any IMAP [RFC3501]
implementation which returns "ANNOTATEMORE" as one of the supported
capabilities in the CAPABILITY command response.

The goal of ANNOTATEMORE is to provide a means for clients to store
and retrieve "metadata" on an IMAP server. The metadata can be
associated with specific mailboxes or the server as a whole.

The ANNOTATEMORE extension adds two new commands and one new untagged
response to the IMAP4 IMAP base protocol.

This extension makes the following changes to the IMAP4 IMAP protocol:

adds a new SETANNOTATION command
adds a new GETANNOTATION command
adds a new ANNOTATION untagged response
adds a new ANNOTATEMORE response code

The data model used in ANNOTATEMORE is exactly the same as that used
in the ANNOTATE [ANNOTATE] extension to IMAP4. IMAP. This is modeled after
that of the Application Configuration Access Protocol [RFC2244] with
the exception of inheritance which is not deemed necessary here.

The rest of this document describes the data model and protocol
changes more rigorously.

2. Data Model

2.1 Overview

The data model used in ANNOTATEMORE is one of a uniquely named entry
with a set of uniquely named attributes, each of which has a value.
Annotations can be added to mailboxes when a mailbox name is provided
as the first argument to the new commands, or to the server as a
whole when the empty string is provided as the first argument to the
new commands.

An annotation can contain multiple named entries. For example, a
general comment being added to a mailbox may have an entry name of "/
comment". This entry could include named attributes such as "value",
"modifiedsince", "acl"
"size", "content-type" etc to represent properties and data
associated with the entry.

The protocol changes to IMAP described below allow a client to access
or change the values of any attributes in any entries in an
annotation, assuming it has sufficient access rights to do so.

Daboo Expires October 18, 2004 April 1, 2005 [Page 4]
Internet-Draft IMAP ANNOTATEMORE Extension April October 2004

2.2 Namespace of entries and attributes

Each annotation is made up of a set of entries. Each entry has a
hierarchical name in UTF-8, with each component of the name separated
by a slash ("/").

Each entry is made up of a set of attributes. Each attribute has a
hierarchical name in UTF-8, with each component of the name separated
by a period (".").

The value of an attribute is NIL (has no value), or a string of zero
or more octets.

Entry and attribute names are not permitted to contain asterisk ("*")
or percent ("%") characters and MUST be valid UTF-8 strings which do
not contain NUL. Invalid entry or attribute names result in a BAD
response in any IMAP commands where they are used.

Use of non-visible UTF-8 characters in entry and attribute names is
discouraged.

This specification defines an initial set of entry and attribute
names available for use with mailbox and server annotations. In
addition an extension mechanism is described to allow additional
names to be added for extensibility.

2.2.1 Entry Names

Entry names MUST be specified in a standards track or IESG approved
experimental RFC, or fall under the vendor namespace. See Section
5.1 for the registration template. This specification only allows
two top-level entry types for servers and mailboxes.

2.2.1.1 Server Entries

These entries are used when the mailbox name argument to the new
commands is the empty string.

/comment
Defines a comment or note associated with the server.

/motd
Defines a "message of the day" for the server. This entry is
always read-only - clients cannot change it.

/admin
Indicates a method for contacting the server administrator. This
may be a URI (e.g. a mailto URL) or other contact information,

Daboo Expires October 18, 2004 April 1, 2005 [Page 5]
Internet-Draft IMAP ANNOTATEMORE Extension April October 2004

such as a telephone number. This entry is always read-only -
clients cannot change it.

/vendor/<vendor-token>
Defines the top-level of entries associated with the server as
created by a particular product of some vendor. This entry can be
used by vendors to provide server or client specific attributes.
The vendor-token MUST be registered with IANA, using the ACAP
[RFC2244] vendor subtree registry.

2.2.1.2 Mailbox Entries

These entries are used when the mailbox name argument to the new
commands is not the empty string.

/comment
Defines a comment or note associated with a mailbox.

/sort
Defines the default sort criteria [SORT] to use when first
displaying the mailbox contents to the user, or NIL if sorting is
not required.

/thread
Defines the default thread criteria [SORT] to use when first
displaying the mailbox contents to the user, or NIL if threading
is not required. If both sort and thread are not NIL, then
threading should take precedence over sorting.

/check
Boolean value "true" or "false" that indicates whether this
mailbox should be checked at regular intervals by the client. The
interval in minutes is specified by the /checkperiod entry.

/checkperiod
Numeric value indicating a period of minutes to use for checking a
mailbox that has the /check entry set to "true".

/vendor/<vendor-token>
Defines the top-level of entries associated with a specific
mailbox as created by a particular product of some vendor. This
entry can be used by vendors to provide client specific
attributes. The vendor-token MUST be registered with IANA, using
the ACAP [RFC2244] vendor subtree registry.

2.2.2 Attribute Names

Attribute names MUST be specified in a standards track or IESG

Daboo Expires October 18, 2004 April 1, 2005 [Page 6]
Internet-Draft IMAP ANNOTATEMORE Extension April October 2004

approved experimental RFC, or fall under the vendor namespace. See
Section 5.1 for the registration template.

All attribute names implicitly have a ".priv" and a ".shared" suffix
which maps to private and shared versions of the entry. Searching or
fetching without using either suffix includes both. The client MUST
specify either a ".priv" or ".shared" suffix when storing an
annotation.

value
The data value of the attribute.

size
The size of the value, in octets. Set automatically by the
server, read-only to clients.

modifiedsince
An opaque value set by the server when this entry is modified. It
can be used by the client to request notification of which entries
have changed since a particular point in time and is useful for
disconnected/synchronisation operations.

content-type
A MIME [RFC2046] content type and subtype that describes the
nature of the content of the "value" attribute.

content-language
Indicates the language used for the value. This follows the
format described in [RFC3282]. Clients SHOULD set this value when
storing an annotation that uses text that can be presented to the
user. It is not required for enumerated or numeric values such as
flags etc.

vendor.<vendor-token>
Defines an attribute associated with a particular product of some
vendor. This attribute can be used by vendors to provide client
specific attributes. The vendor-token MUST be registered with
IANA, using the ACAP [RFC2244] vendor subtree registry.

2.3 Private versus Shared and Access Control

As discussed in the ANNOTATE [ANNOTATE] extension there is a need to
support both private and shared annotations. This document adopts
the scheme used in [ANNOTATE] that adds two standard suffixes for all
attributes: ".shared" and ".priv". A GETANNOTATION command which
specifies neither uses both. SETANNOTATION commands MUST explicitly
use .priv or .shared suffixes.

A user can only store and retrieve private or shared annotations on a
mailbox which is returned to them via a LIST or LSUB command. A user can only
store and retrieve shared annotations on a mailbox that they can
SELECT and which opens READ-WRITE. A user can only retrieve shared
annotations on a mailbox that they can SELECT and which opens
READ-ONLY. If a the
client attempts to store a shared annotation or retrieve annotations on a
READ-ONLY mailbox, other mailboxes,
the server MUST respond with a NO response. response

Daboo Expires October 18, 2004 April 1, 2005 [Page 7]
Internet-Draft IMAP ANNOTATEMORE Extension April October 2004

3. IMAP Protocol Changes

3.1 General Considerations

The new commands and response each have a mailbox name argument,
indicating that the annotations being referred to are attached to the
specified mailbox. An empty string can be used for the mailbox name
to signify server annotations.

Both "*" and "%" list wildcard characters MAY be used in the mailbox
name argument to commands to match all possible occurrences of a
mailbox name pattern. However, "*" or "%" by themselves MUST NOT
match the empty string (server) entries. Server entries can only be
accessed by explicitly using the empty string as the mailbox name.

Servers SHOULD ensure that mailbox annotations are automatically
moved when the mailbox they refer to is renamed, i.e. the
annotations follow the mailbox. Servers SHOULD delete annotations
for a mailbox when the mailbox is deleted, so that a mailbox created
with the same name as a previously existing mailbox does not inherit
the old mailbox annotations. Servers SHOULD allow annotations on all
'types' of mailbox, including ones reporting \Noselect for their LIST
response. Servers can implicitly remove \Noselect mailboxes when all
child mailboxes are removed, and as such any annotations associated
with the \Noselect mailbox SHOULD be removed.

The server is allowed to impose limitations on the size of any one
annotation or the total number of annotations for a single mailbox or
for the server as a whole. However, the server MUST accept a minimum
annotation data size of at least 1024 bytes, and a minimum annotation
count per server or mailbox of at least 10.

3.2 GETANNOTATION Command

This extension adds the GETANNOTATION command. This allows clients
to retrieve annotations.

This command is only available in authenticated or selected state
[RFC3501].

Arguments: mailbox-name
entry-specifier
attribute-specifier

Responses: required ANNOTATION response

Result: OK - command completed
NO - command failure: can't access annotations on that mailbox

Daboo Expires October 18, 2004 April 1, 2005 [Page 8]
Internet-Draft IMAP ANNOTATEMORE Extension April October 2004

BAD - command unknown or arguments invalid

The mailbox-name argument MUST be a valid mailbox name or the empty
string. In the later case, the annotations being referred to are the
ones for the server as a whole.

Example:

C: a GETANNOTATION "" "/comment" "value.priv"
S: * ANNOTATION "" "/comment" ("value.priv" "My comment")
S: a OK GETANNOTATION complete

In the above example, the contents of the "value" attribute for
the "/comment" server entry is requested by the client and
returned by the server.

"*" and "%" wildcard characters can be used in either specifier to
match one or more characters at that position, with the exception
that "%" does not match the hierarchy delimiter for the specifier it
appears in (i.e. "/" for an entry specifier or "." for an attribute
specifier). Thus an entry specifier of "/%" would match entries such
as "/comment" and "/version", but not "/comment/note".

Example:

C: a GETANNOTATION "" "/*" "value.priv"
S: * ANNOTATION "" "/comment" ("value.priv" "My comment")
"/version" ("value.priv" "1.1")
"/motd/today" ("value.priv" "Closed at 1 pm")
S: a OK GETANNOTATION complete

In the above example, the contents of the "value" attributes for
any server entries are requested by the client and returned by the
server.

Example:

C: a GETANNOTATION "" "/%" "value"
S: * ANNOTATION "/comment" ("value.priv" "My comment")
("value.shared" "Your comment")
"/motd" ("value.priv" "Its sunny outside!"
("value.shared" "Today is a Holiday")
S: a OK GETANNOTATION complete

In the above example, the contents of the "value" attributes for
server entries at the top level of the entry hierarchy only, are
requested by the client and returned by the server. Both the
.priv and .shared values are returned, as neither were explicitly

Daboo Expires October 18, 2004 April 1, 2005 [Page 9]
Internet-Draft IMAP ANNOTATEMORE Extension April October 2004

requested.

Entry and attribute specifiers can be lists of atomic specifiers, so
that multiple items of each type may be returned in a single
GETANNOTATION command.

Example:

C: a GETANNOTATION "" ("/comment" "/motd") "value.priv"
S: * ANNOTATION "" "/comment" ("value.priv" "My comment")
"/motd" ("value.priv" "Its sunny outside!")
S: a OK GETANNOTATION complete

In the above example, the contents of the "value" attributes for
the two server entries "/comment" and "/motd" are requested by the
client and returned by the server.

Example:

C: a GETANNOTATION "" "/comment" ("value.priv" "modifiedsince.priv") "content-type.priv")
S: * ANNOTATION "" "/comment" ("value.priv" "My comment"
"modifiedsince.priv" "19990203205432")
"content-type.priv" "text/plain")
S: a OK GETANNOTATION complete

In the above example, the contents of the "value" and
"modifiedsince"
"content-type" attributes for the "/comment" server entry are
requested by the client and returned by the server.

3.3 SETANNOTATION Command

This extension adds the SETANNOTATION command. This allows clients
to set annotations.

This command is only available in authenticated or selected state
[RFC3501].

Arguments: mailbox-name
entry
attribute-value
list of entry, attribute-values

Responses: no specific responses for this command

Result: OK - command completed
NO - command failure: can't set annotations,
or annotation too big or too many
BAD - command unknown or arguments invalid

Daboo Expires October 18, 2004 April 1, 2005 [Page 10]
Internet-Draft IMAP ANNOTATEMORE Extension April October 2004

Sets the specified list of entries by adding or replacing the
specified attributes with the values provided. Clients can use NIL
for values of attributes it wants to remove from entries. The server
MAY return an unsolicited ANNOTATION response containing the updated
annotation data. The server SHOULD send such responses for any
changes to the server annotations, and SHOULD send such responses for
mailbox annotations only for the currently selected mailbox. Clients
MUST NOT assume that an unsolicited ANNOTATION response will be sent,
and MUST assume that if the command succeeds then the annotation has
been changed.

If the server is unable to store an annotation because the size of
its value is too large, the server MUST return a tagged NO response
with a "[ANNOTATEMORE TOOBIG]" response code.

If the server is unable to store a new annotation because the maximum
number of allowed annotations has already been reached, the server
MUST return a tagged NO response with a "[ANNOTATEMORE TOOMANY]"
response code.

If the server is unable to store the annotations for one or more
mailboxes matching the mailbox-name pattern, then the SETANNOTATION
command MUST fail and there MUST NOT be any changes to any of the
matching mailboxes, even those for which annotations could have been
changed successfully.

Example:

C: a SETANNOTATION "INBOX" "/comment" ("value.priv" "My new comment")
S: a OK SETANNOTATION complete

In the above example, the entry "/comment" for the mailbox "INBOX"
is created (if not already present) and the private attribute
"value" with data set to "My new comment" is created if not
already present, or replaced if it previously exists.

Example:

C: a SETANNOTATION "INBOX" "/comment" ("value.priv" NIL)
S: a OK SETANNOTATION complete

In the above example, the private "value" attribute of the entry
"/comment" is removed from the mailbox "INBOX".

Multiple entries can be set in a single SETANNOTATION command by
listing entry-attribute-value pairs in the list.

Example:

Daboo Expires October 18, 2004 April 1, 2005 [Page 11]
Internet-Draft IMAP ANNOTATEMORE Extension April October 2004

C: a SETANNOTATION "INBOX.%" "/comment" ("value.priv" "My new comment")
S: a OK SETANNOTATION complete

In the above example, the entry "/comment" for all mailboxes at
the top-level of the "INBOX" hierarchy are created (if not already
present) and the private and shared attributes "value" are created
respectively for each entry if not already present, or replaced if
they previously existed.

Multiple attributes can be set in a single SETANNOTATION command by
listing multiple attribute-value pairs in the entry list.

Example:

C: a SETANNOTATION "INBOX" "/comment"
("value.priv" "My new comment"
"vendor.foobar.bloop.priv" "foo's bar")
S: a OK SETANNOTATION complete

In the above example, the entry "/comment" for the mailbox "INBOX"
is created (if not already present) and the private attributes
"value" and "vendor.foobar.bloop" are created if not already
present, or replaced if they previously existed.

Example:

C: a SETANNOTATION "INBOX" "/comment" ("value.priv" "My new comment")
S: a NO [ANNOTATEMORE TOOMANY] SETANNOTATION failed

In the above example, the server is unable to store the requested
(new) annotation as it has reached the limit on the number of
annotations it can support on the specified mailbox.

3.4 ANNOTATION Response

The ANNOTATION response displays results of a GETANNOTATION command,
or can be returned as a unsolicited response at anytime by the server
in response to a change in an annotation.

Servers SHOULD send unsolicited ANNOTATION responses if changed by a
third-party, allowing servers to keep clients updated with changes to
annotations by other clients. Unsolicited mailbox entries MUST only
be returned for the currently selected mailbox. In this case, only
the entries are returned in this case, only
the entries are returned in the ANNOTATION response, not the
attributes and values. If the client wants to update any cached
values it must explicitly retrieve those using a GETANNOTATION
command.

Daboo Expires April 1, 2005 [Page 12]
Internet-Draft IMAP ANNOTATEMORE Extension October 2004

Separate ANNOTATION responses MUST be used when more than one mailbox
matches the mailbox name argument pattern to the command.

The ANNOTATION response can contain multiple entries in a single
response, but the server is free to return multiple responses for
each entry or group of entries if it desires.

This response is only available in authenticated state [RFC3501].

3.4.1 ANNOTATION response with attributes and values

The response consists of a list of entries each of which has a list
of attribute-value pairs.

Example:

C: a GETANNOTATION "" "/comment" "value.priv"
S: * ANNOTATION "" "/comment" ("value.priv" "My comment")
S: a OK GETANNOTATION complete

In the above example, a single entry with a single attribute-value
pair is returned by the server.

Example:

C: a GETANNOTATION "" ("/comment" "/motd") "value.priv"
S: * ANNOTATION "" "/comment" ("value.priv" "My comment")
"/motd" ("value.priv" "Its sunny outside!")
S: a OK GETANNOTATION complete

In the above example, two entries each with a single
attribute-value pair is returned by the server.

Example:

C: a GETANNOTATION "" ("/comment" "/motd") "value.priv"
S: * ANNOTATION "" "/comment" ("value.priv" "My comment")
S: * ANNOTATION "" "/motd" ("value.priv" "Its sunny outside!")
S: a OK GETANNOTATION complete

In the ANNOTATION response, not above example, the
attributes and values. If server returns two separate responses
for each of the client wants to update any cached
values it must explicitly retrieve those using two entries requested.

Example:

C: a GETANNOTATION
command. "" "/comment" ("value.priv" "size.priv")
S: * ANNOTATION "" "/comment" ("value.priv" "My comment"
"size.priv" "10")

Daboo Expires October 18, 2004 April 1, 2005 [Page 12] 13]
Internet-Draft IMAP ANNOTATEMORE Extension April October 2004

Separate ANNOTATION responses MUST be used when more than one mailbox
matches

S: a OK GETANNOTATION complete

In the mailbox name argument pattern to above example, a single entry with two attribute-value
pairs is returned by the command.

The server.

Example:

C: a GETANNOTATION "INBOX.%" "/comment" "value.priv"
S: * ANNOTATION response can contain multiple entries in "INBOX.1" "/comment" ("value.priv" "My comment for 1")
S: * ANNOTATION "INBOX.2" "/comment" ("value.priv" "My comment for 2")
S: * ANNOTATION "INBOX.3" "/comment" ("value.priv" "My comment for 3")
S: a single
response, but OK GETANNOTATION complete

In the server is free to return multiple above example, separate responses are returned for each
matching mailbox, each containing a single entry or group of entries if it desires.

This response is only available in authenticated state [RFC3501].

3.4.1 with a single
attribute-value pair.

3.4.2 Unsolicited ANNOTATION response with without attributes and values

The response consists of a list of entries each of which has parenthesised list of entries, each of
which have changed on the server.

Example:

C: a NOOP
S: * ANNOTATION "" ("/comment")
S: a OK NOOP complete

In the above example, the server indicates that the "/comment"
server entry has been changed.

Example:

C: a NOOP
S: * ANNOTATION "" ("/comment" "/motd")
S: a OK NOOP complete

In the above example, the server indicates a list
of attribute-value pairs. change to two server
entries.

Example:

C: a GETANNOTATION "" "/comment" "value.priv" NOOP
S: * ANNOTATION "" "/comment" ("value.priv" "My comment") ("/motd")
S: * ANNOTATION "INBOX" ("/comment")
S: a OK GETANNOTATION NOOP complete

Daboo Expires April 1, 2005 [Page 14]
Internet-Draft IMAP ANNOTATEMORE Extension October 2004

In the above example, the server indicates a single change to a server
entry, and to the an entry for the currently selected mailbox.

4. Formal Syntax

The following syntax specification uses the Augmented Backus-Naur
Form (ABNF) notation as specified in [RFC2234].

Non-terminals referenced but not defined below are as defined by
[RFC3501].

Except as noted otherwise, all alphabetic characters are case-
insensitive. The use of upper or lower case characters to define
token strings is for editorial clarity only. Implementations MUST
accept these strings in a case-insensitive fashion.

annotate-data = "ANNOTATION" SP mailbox SP entry-list
; empty string for mailbox implies
; server annotation.

att-value = attrib SP value

attrib = string
; dot-separated attribute name
; MUST NOT contain "*" or "%"
attrib-match = string
; dot-separated attribute name
; MAY contain "*" or "%" for use as wildcards

attribs = attrib-match / "(" attrib-match *(SP attrib-match) ")"
; attribute specifiers that can include wildcards

command-auth /= setannotation / getannotation
; adds to original IMAP command

entries = entry-match / "(" entry-match *(SP entry-match) ")"
; entry specifiers that can include wildcards

entry = string
; slash-separated path to entry
; MUST NOT contain "*" or "%"

entry-att = entry SP "(" att-value *(SP att-value) ")"

entry-list = entry-att *(SP entry-att) /
"(" entry *(SP entry) ")"
; entry with a single attribute-value
pair is returned by the server.

Example:

C: a GETANNOTATION "" ("/comment" "/motd") "value.priv"
S: * ANNOTATION "" "/comment" ("value.priv" "My comment")
"/motd" ("value.priv" "Its sunny outside!")
S: a OK pairs list for
; GETANNOTATION complete

In the above example, two response, or

Daboo Expires April 1, 2005 [Page 15]
Internet-Draft IMAP ANNOTATEMORE Extension October 2004

; parenthesised entry list for unsolicited
; notification of annotation changes

entry-match = string
; slash-separated path to entry
; MAY contain "*" or "%" for use as wildcards

getannotation = "GETANNOTATION" SP list-mailbox SP entries each with a single
attribute-value pair is returned by the server.

Example:

In the above example, the SP attribs
; empty string for list-mailbox implies
; server returns two separate annotation.

response-data /= "*" SP annotate-data CRLF
; adds to original IMAP data responses

resp-text-code =/ "ANNOTATEMORE" SP "TOOBIG" /
"ANNOTATEMORE" SP "TOOMANY"
; new response codes for each of the two entries requested.

Example:

C: SETANNOTATION failures

setannotation = "SETANNOTATION" SP list-mailbox SP setentryatt
; empty string for list-mailbox implies
; server annotation.

setentryatt = entry-att / "(" entry-att *(SP entry-att) ")"

value = nstring

5. IANA Considerations

Both entry names and attribute names MUST be specified in a GETANNOTATION "" "/comment" ("value.priv" "modifiedsince.priv")
S: * ANNOTATION "" "/comment" ("value.priv" "My comment"
"modifiedsince.priv" "19990203205432") standards
track or IESG approved experimental RFC, or fall under the vendor
namespace.

Daboo Expires October 18, 2004 April 1, 2005 [Page 13] 16]
Internet-Draft IMAP ANNOTATEMORE Extension April October 2004

S: a OK GETANNOTATION complete

In the above example, a single entry with two attribute-value
pairs is returned by the server.

Example:

C: a GETANNOTATION "INBOX.%" "/comment" "value.priv"
S: * ANNOTATION "INBOX.1" "/comment" ("value.priv" "My comment for 1")
S: * ANNOTATION "INBOX.2" "/comment" ("value.priv" "My comment for 2")
S: * ANNOTATION "INBOX.3" "/comment" ("value.priv" "My comment for 3")
S: a OK GETANNOTATION complete

In the above example, separate responses are returned for each
matching mailbox, each containing a single entry with a single
attribute-value pair.

3.4.2 Unsolicited ANNOTATION response without attributes

5.1 Entry and values Attribute Registration Template

To: iana@iana.org
Subject: IMAP ANNOTATEMORE Registration

Please register the following IMAP ANNOTATEMORE item:

[ ] Entry [ ] Attribute

[ ] Mailbox [ ] Server

Name: ______________________________

Description: _______________________

____________________________________

Contact person: ____________________

email: ____________________

5.2 Server Entry Registrations

The response consists of a parenthesised list of entries, each following templates specify the IANA registrations of
which have changed on annotation
entries specified in this document.

5.2.1 /comment

To: iana@iana.org
Subject: IMAP ANNOTATEMORE Registration

Please register the server.

Example:

C: a NOOP
S: * ANNOTATION "" ("/comment")
S: a OK NOOP complete

In following IMAP ANNOTATEMORE item:

[x] Entry [ ] Attribute

[ ] Mailbox [x] Server

Name: /comment

Description: Defined in IMAP ANNOTATEMORE extension document.

Contact person: Cyrus Daboo

email: daboo@isamet.com

Daboo Expires April 1, 2005 [Page 17]
Internet-Draft IMAP ANNOTATEMORE Extension October 2004

5.2.2 /motd

To: iana@iana.org
Subject: IMAP ANNOTATEMORE Registration

Please register the above example, following IMAP ANNOTATEMORE item:

[x] Entry [ ] Attribute

[ ] Mailbox [x] Server

Name: /motd

Description: Defined in IMAP ANNOTATEMORE extension document.

Contact person: Cyrus Daboo

email: daboo@isamet.com

5.2.3 /admin

To: iana@iana.org
Subject: IMAP ANNOTATEMORE Registration

Please register the server indicates that following IMAP ANNOTATEMORE item:

[x] Entry [ ] Attribute

[ ] Mailbox [x] Server

Name: /admin

Description: Defined in IMAP ANNOTATEMORE extension document.

Contact person: Cyrus Daboo

email: daboo@isamet.com

5.3 Mailbox Entry Registrations

The following templates specify the "/comment"
server entry has been changed.

Example:

C: a NOOP
S: * ANNOTATION "" ("/comment" "/motd")
S: a OK NOOP complete

In IANA registrations of annotation
entries specified in this document.

Daboo Expires April 1, 2005 [Page 18]
Internet-Draft IMAP ANNOTATEMORE Extension October 2004

5.3.1 /comment

To: iana@iana.org
Subject: IMAP ANNOTATEMORE Registration

Please register the above example, following IMAP ANNOTATEMORE item:

[x] Entry [ ] Attribute

[x] Mailbox [ ] Server

Name: /comment

Description: Defined in IMAP ANNOTATEMORE extension document.

Contact person: Cyrus Daboo

email: daboo@isamet.com

5.3.2 /sort

To: iana@iana.org
Subject: IMAP ANNOTATEMORE Registration

Please register the server indicates a change to two server
entries.

Example:

C: a NOOP
S: * ANNOTATION "" ("/motd")
S: * ANNOTATION "INBOX" ("/comment")
S: a OK NOOP complete following IMAP ANNOTATEMORE item:

[x] Entry [ ] Attribute

[x] Mailbox [ ] Server

Name: /sort

Description: Defined in IMAP ANNOTATEMORE extension document.

Contact person: Cyrus Daboo

email: daboo@isamet.com

Daboo Expires April 1, 2005 [Page 19]
Internet-Draft IMAP ANNOTATEMORE Extension October 18, 2004

5.3.3 /thread

To: iana@iana.org
Subject: IMAP ANNOTATEMORE Registration

Please register the following IMAP ANNOTATEMORE item:

[x] Entry [ ] Attribute

[x] Mailbox [ ] Server

Name: /thread

Description: Defined in IMAP ANNOTATEMORE extension document.

Contact person: Cyrus Daboo

email: daboo@isamet.com

5.3.4 /check

To: iana@iana.org
Subject: IMAP ANNOTATEMORE Registration

Please register the following IMAP ANNOTATEMORE item:

[x] Entry [ ] Attribute

[x] Mailbox [ ] Server

Name: /check

Description: Defined in IMAP ANNOTATEMORE extension document.

Contact person: Cyrus Daboo

email: daboo@isamet.com

Daboo Expires April 1, 2005 [Page 14] 20]
Internet-Draft IMAP ANNOTATEMORE Extension April 2004

In the above example, the server indicates a change to a server
entry, and to the an entry for the currently selected mailbox.

4. Formal Syntax Extension October 2004

5.3.5 /checkperiod

To: iana@iana.org
Subject: IMAP ANNOTATEMORE Registration

Please register the following IMAP ANNOTATEMORE item:

[x] Entry [ ] Attribute

[x] Mailbox [ ] Server

Name: /checkperiod

Description: Defined in IMAP ANNOTATEMORE extension document.

Contact person: Cyrus Daboo

email: daboo@isamet.com

5.4 Attribute Registrations

The following syntax specification uses templates specify the Augmented Backus-Naur
Form (ABNF) notation as specified in [RFC2234].

Non-terminals referenced but not defined below are as defined by
[RFC3501].

Except as noted otherwise, all alphabetic characters are case-
insensitive. The use IANA registrations of upper or lower case characters to define
token strings is for editorial clarity only. Implementations MUST
accept these strings annotation
attributes specified in a case-insensitive fashion.

annotate-data = "ANNOTATION" SP mailbox SP entry-list
; empty string for mailbox implies
; server annotation.

att-value = attrib SP this document.

5.4.1 value

attrib = string
; dot-separated attribute name
; MUST NOT contain "*" or "%"
attrib-match = string
; dot-separated attribute name
; MAY contain "*" or "%" for use as wildcards

attribs = attrib-match / "(" attrib-match *(SP attrib-match) ")"
; attribute specifiers that can include wildcards

command-auth /= setannotation / getannotation
; adds to original IMAP4 command

entries = entry-match / "(" entry-match *(SP entry-match) ")"
; entry specifiers that can include wildcards

entry = string
; slash-separated path to entry
; MUST NOT contain "*" or "%"

entry-att = entry SP "(" att-value *(SP att-value) ")"

entry-list = entry-att *(SP entry-att) /
"(" entry *(SP entry) ")"
; entry attribute-value pairs list for
; GETANNOTATION response, or

To: iana@iana.org
Subject: IMAP ANNOTATEMORE Registration

Please register the following IMAP ANNOTATEMORE item:

[ ] Entry [x] Attribute

[ ] Mailbox [ ] Server

Name: value

Description: Defined in IMAP ANNOTATEMORE extension document.

Contact person: Cyrus Daboo

email: daboo@isamet.com

Daboo Expires October 18, 2004 April 1, 2005 [Page 15] 21]
Internet-Draft IMAP ANNOTATEMORE Extension April October 2004

; parenthesised entry list for unsolicited
; notification of annotation changes

entry-match = string
; slash-separated path to entry
; MAY contain "*" or "%" for use as wildcards

getannotation = "GETANNOTATION" SP list-mailbox SP entries SP attribs
; empty string for list-mailbox implies
; server annotation.

response-data /= "*" SP annotate-data CRLF
; adds to original IMAP4 data responses

resp-text-code =/ "ANNOTATEMORE" SP "TOOBIG" /
"ANNOTATEMORE" SP "TOOMANY"
; new response codes for SETANNOTATION failures

setannotation = "SETANNOTATION" SP list-mailbox SP setentryatt
; empty string for list-mailbox implies
; server annotation.

setentryatt = entry-att / "(" entry-att *(SP entry-att) ")"

value = nstring

5. IANA Considerations

Both entry names and attribute names MUST be specified

5.4.2 size

To: iana@iana.org
Subject: IMAP ANNOTATEMORE Registration

Please register the following IMAP ANNOTATEMORE item:

[ ] Entry [x] Attribute

[ ] Mailbox [ ] Server

Name: size

Description: Defined in a standards
track or IESG approved experimental RFC, or fall under IMAP ANNOTATEMORE extension document.

Contact person: Cyrus Daboo

email: daboo@isamet.com

5.4.3 content-type

To: iana@iana.org
Subject: IMAP ANNOTATEMORE Registration

Please register the vendor
namespace. following IMAP ANNOTATEMORE item:

[ ] Entry [x] Attribute

[ ] Mailbox [ ] Server

Name: content-type

Description: Defined in IMAP ANNOTATEMORE extension document.

Contact person: Cyrus Daboo

email: daboo@isamet.com

Daboo Expires October 18, 2004 April 1, 2005 [Page 16] 22]
Internet-Draft IMAP ANNOTATEMORE Extension April October 2004

5.1 Entry and Attribute Registration Template

5.4.4 content-language

To: iana@iana.org
Subject: IMAP ANNOTATEMORE Registration

Please register the following IMAP ANNOTATEMORE item:

[]

[ ] Entry [] [x] Attribute

[]

[ ] Mailbox [] [ ] Server

Name: ______________________________ content-language

Description: _______________________

____________________________________

____________________________________ Defined in IMAP ANNOTATEMORE extension document.

Contact person: ____________________ Cyrus Daboo

email: ____________________ daboo@isamet.com

6. Security Considerations

The

Annotations whose values are intended to remain private MUST be
stored in .priv values, and not .shared values which may be
accessible to other users.

>Excluding the above issues the ANNOTATEMORE extension does not raise
any security considerations that are not present in the base [RFC3501] IMAP
protocol, and these issues are discussed in [RFC3501].

Care must be taken to ensure that annotations whose values are
intended to remain private are not stored in mailboxes which are
accessible to other users. This includes mailboxes owned by the user
by whose ACLs permit access by others as well as any shared
mailboxes.

7. References

7.1 Normative References

[RFC2046] Freed, N. and N. Borenstein, "Multipurpose Internet Mail
Extensions (MIME) Part Two: Media Types", RFC 2046,
November 1996.

[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119, March 1997.

[RFC2234] Crocker, D. and P. Overell, "Augmented BNF for Syntax
Specifications: ABNF", RFC 2234, November 1997.

Daboo Expires October 18, 2004 [Page 17]

Internet-Draft IMAP ANNOTATEMORE Extension April 2004

[RFC2244] Newman, C. and J. Myers, "ACAP -- Application
Configuration Access Protocol", RFC 2244, November 1997.

[RFC3282] Alvestrand, H., "Content Language Headers", RFC 3282, May

Daboo Expires April 1, 2005 [Page 23]
Internet-Draft IMAP ANNOTATEMORE Extension October 2004

2002.

[RFC3501] Crispin, M., "INTERNET MESSAGE ACCESS PROTOCOL - VERSION
4rev1", RFC 3501, March 2003.

[SORT] Crispin, M. and K. Murchison, "Internet Message Access
Protocol - Sort and Thread Extension",
draft-ietf-imapext-sort-15.txt, April
draft-ietf-imapext-sort-17.txt, May 2004.

7.2 Informative References

[ANNOTATE]
Daboo, C. and R. Gellens, "IMAP ANNOTATE Extension",
draft-ietf-imapext-annotate-09.txt, April
draft-ietf-imapext-annotate-11.txt, October 2004.

Author's Address

Cyrus Daboo
Cyrusoft International,
ISAMET, Inc.
5001 Baum Blvd.
Suite 650
Pittsburgh, PA 15213
US

EMail: daboo@cyrusoft.com daboo@isamet.com

Appendix A. Acknowledgments

The ideas expressed in this document are based on the message
annotation document that was co-authored by Randall Gellens.

Daboo Expires October 18, 2004 April 1, 2005 [Page 18] 24]
Internet-Draft IMAP ANNOTATEMORE Extension April October 2004

Intellectual Property Statement

The IETF takes no position regarding the validity or scope of any
intellectual property
Intellectual Property Rights or other rights that might be claimed to
pertain to the implementation or use of the technology described in
this document or the extent to which any license under such rights
might or might not be available; neither nor does it represent that it has
made any independent effort to identify any such rights. Information
on the
IETF's procedures with respect to rights in standards-track and
standards-related documentation RFC documents can be
found in BCP-11. BCP 78 and BCP 79.

Copies of
claims of rights IPR disclosures made available for publication to the IETF Secretariat and any
assurances of licenses to be made available, or the result of an
attempt made to obtain a general license or permission for the use of
such proprietary rights by implementors implementers or users of this
specification can be obtained from the IETF Secretariat. on-line IPR repository at
http://www.ietf.org/ipr.

The IETF invites any interested party to bring to its attention any
copyrights, patents or patent applications, or other proprietary
rights which that may cover technology that may be required to practice implement
this standard. Please address the information to the IETF Executive
Director.

Full Copyright Statement

This document and translations of it may be copied and furnished to
others, and derivative works that comment on or otherwise explain it
or assist in its implementation may be prepared, copied, published
and distributed, in whole or in part, without restriction of any
kind, provided that the above copyright notice and this paragraph are
included on all such copies and derivative works. However, this
document itself may not be modified in any way, such as by removing
the copyright notice or references to the Internet Society or other
Internet organizations, except as needed for the purpose at
ietf-ipr@ietf.org.

Disclaimer of
developing Internet standards in which case the procedures for
copyrights defined in the Internet Standards process must be
followed, or as required to translate it into languages other than
English.

The limited permissions granted above are perpetual and will not be
revoked by the Internet Society or its successors or assignees. Validity

This document and the information contained herein is are provided on an
"AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS
OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY AND THE INTERNET
ENGINEERING TASK FORCE DISCLAIMS DISCLAIM ALL WARRANTIES, EXPRESS OR IMPLIED,
INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE
INFORMATION

Daboo Expires October 18, 2004 [Page 19]

Internet-Draft IMAP ANNOTATEMORE Extension April 2004 HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED
WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.

Copyright (C) The Internet Society (2004). This document is subject
to the rights, licenses and restrictions contained in BCP 78, and
except as set forth therein, the authors retain all their rights.

Acknowledgment

Funding for the RFC Editor function is currently provided by the
Internet Society.

Daboo Expires October 18, 2004 April 1, 2005 [Page 20] 25]
----