< draft-ietf-imapext-annotate-03.txt		draft-ietf-imapext-annotate-04.txt >
	IMAP Extensions Working Group R. Gellens		IMAP Extensions Working Group R. Gellens
	Internet Draft: IMAP ANNOTATE Extension C. Daboo		Internet Draft: IMAP ANNOTATE Extension C. Daboo
	Document: draft-ietf-imapext-annotate-03.txt January 2002		Document: draft-ietf-imapext-annotate-04.txt March 2002
	IMAP ANNOTATE Extension		IMAP ANNOTATE Extension
	Status of this Memo		Status of this Memo
	This document is an Internet-Draft and is in full conformance with		This document is an Internet-Draft and is in full conformance with
	all provisions of Section 10 of RFC2026.		all provisions of Section 10 of RFC2026.
	Internet-Drafts are working documents of the Internet Engineering		Internet-Drafts are working documents of the Internet Engineering
	Task Force (IETF), its areas, and its working groups. Note that		Task Force (IETF), its areas, and its working groups. Note that
	skipping to change at page 19, line ? ¶		skipping to change at page 2, line 14 ¶
	Table of Contents		Table of Contents
	1 Abstract . . . . . . . . . . . . . . . . . . . . . . . . . . 2		1 Abstract . . . . . . . . . . . . . . . . . . . . . . . . . . 2
	2 Discussion . . . . . . . . . . . . . . . . . . . . . . . . . 2		2 Discussion . . . . . . . . . . . . . . . . . . . . . . . . . 2
	3 Conventions Used in This Document . . . . . . . . . . . . . . 2		3 Conventions Used in This Document . . . . . . . . . . . . . . 2
	4 Change History . . . . . . . . . . . . . . . . . . . . . . . 3		4 Change History . . . . . . . . . . . . . . . . . . . . . . . 3
	5 Introduction and Overview . . . . . . . . . . . . . . . . . . 4		5 Introduction and Overview . . . . . . . . . . . . . . . . . . 4
	6 Data Model . . . . . . . . . . . . . . . . . . . . . . . . . 5		6 Data Model . . . . . . . . . . . . . . . . . . . . . . . . . 5
	6.1 Overview . . . . . . . . . . . . . . . . . . . . . . . . 5		6.1 Overview . . . . . . . . . . . . . . . . . . . . . . . . 5
	6.2 Namespace of Entries and Attributes . . . . . . . . . . 5		6.2 Namespace of Entries and Attributes . . . . . . . . . . 5
	6.2.1 Entry Names . . . . . . . . . . . . . . . . . . . . . 5		6.2.1 Entry Names . . . . . . . . . . . . . . . . . . . . . 6
	6.2.2 Attribute Names . . . . . . . . . . . . . . . . . . 7		6.2.2 Attribute Names . . . . . . . . . . . . . . . . . . 8
	7 Private versus Shared and Access Control . . . . . . . . . . 8		7 Private versus Shared and Access Control . . . . . . . . . . 8
	8 IMAP Protocol Changes . . . . . . . . . . . . . . . . . . . 9		8 IMAP Protocol Changes . . . . . . . . . . . . . . . . . . . 9
	8.1 Optional parameters with the SELECT/EXAMINE commands . . 9		8.1 Optional parameters with the SELECT/EXAMINE commands . . 9
	8.2 ANNOTATION Message Data Item in FETCH Command . . . . . 10		8.2 ANNOTATION Message Data Item in FETCH Command . . . . . 10
	8.3 ANNOTATION Message Data Item in FETCH Response . . . . . 11		8.3 ANNOTATION Message Data Item in FETCH Response . . . . . 12
	8.4 ANNOTATION Message Data Item in STORE . . . . . . . . . 13		8.4 ANNOTATION Message Data Item in STORE . . . . . . . . . 13
	8.5 ANNOTATION Message Data Item in APPEND . . . . . . . . . 14		8.5 ANNOTATION interaction with COPY . . . . . . . . . . . . 14
	8.6 ANNOTATION Criterion in SEARCH . . . . . . . . . . . . . 14		8.6 ANNOTATION Message Data Item in APPEND . . . . . . . . . 14
	8.7 ANNOTATION Key in SORT . . . . . . . . . . . . . . . . . 15		8.7 ANNOTATION Criterion in SEARCH . . . . . . . . . . . . . 15
	9 Formal Syntax . . . . . . . . . . . . . . . . . . . . . . . 15		8.8 ANNOTATION Key in SORT . . . . . . . . . . . . . . . . . 15
	10 IANA Considerations . . . . . . . . . . . . . . . . . . . . . 17		9 Formal Syntax . . . . . . . . . . . . . . . . . . . . . . . . 16
	10.1 Entry and Attribute Registration Template . . . . . . . 17		10 IANA Considerations . . . . . . . . . . . . . . . . . . . . 18
	11 Security Considerations . . . . . . . . . . . . . . . . . . . 17		10.1 Entry and Attribute Registration Template . . . . . . . . 18
	12 References . . . . . . . . . . . . . . . . . . . . . . . . . 18		11 Security Considerations . . . . . . . . . . . . . . . . . . 18
	13 Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 18		12 References . . . . . . . . . . . . . . . . . . . . . . . . . 18
	14 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . 18		13 Acknowledgments . . . . . . . . . . . . . . . . . . . . . . 19
	15 Full Copyright Statement . . . . . . . . . . . . . . . . . . 19		14 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . 19
			15 Full Copyright Statement . . . . . . . . . . . . . . . . . . 19
	1 Abstract		1 Abstract
	The ANNOTATE extension to the Internet Message Access Protocol		The ANNOTATE extension to the Internet Message Access Protocol
	[IMAP4] permits clients and servers to maintain "metadata" for		[IMAP4] permits clients and servers to maintain "metadata" for
	messages stored in an IMAP4 mailbox.		messages stored in an IMAP4 mailbox.
	2 Discussion		2 Discussion
	Public comments can be sent to the IETF IMAP Extensions mailing		Public comments can be sent to the IETF IMAP Extensions mailing
	skipping to change at page 19, line ? ¶		skipping to change at page 3, line 13 ¶
	document are to be interpreted as described in RFC 2119 [KEYWORDS].		document are to be interpreted as described in RFC 2119 [KEYWORDS].
	Formal syntax is defined using ABNF [ABNF] as modified by [IMAP4].		Formal syntax is defined using ABNF [ABNF] as modified by [IMAP4].
	In examples, "C:" and "S:" indicate lines sent by the client and		In examples, "C:" and "S:" indicate lines sent by the client and
	server respectively. Line breaks not preceded by a "C:" or "S:" are		server respectively. Line breaks not preceded by a "C:" or "S:" are
	for editorial clarity only.		for editorial clarity only.
	4 Change History		4 Change History
			Changes from -03 to -04:
			1. Fixed attrib/attrib-match grammar to use "." instead of "/".
			2. Add text for server to reject unknown <part-specifier>.
			3. Do not allow empty part-specifier.
			4. Store NIL to value to delete.
			5. Comment on COPY interaction with ANNOTATE.
			6. Added comment that IMAP flags are mapped one-to-one with their
			corresponding FLAGS items.
			7. Added comment that the recent flag annotation is read-only.
	Changes from -02 to -03:		Changes from -02 to -03:
	1. Removed reference to status modtime item.		1. Removed reference to status modtime item.
	2. Added missing 'notify' and 'ret' dsn annotations for		2. Added missing 'notify' and 'ret' dsn annotations for
	/message/smtp-envelope.		/message/smtp-envelope.
	3. Added requirement to store data permanently - no		3. Added requirement to store data permanently - no
	'session only' annotations.		'session only' annotations.
	4. Removed Access Control section. Replaced with comments		4. Removed Access Control section. Replaced with comments
	on read-only/read-write mailboxes and storing private or		on read-only/read-write mailboxes and storing private or
	shared annotations.		shared annotations.
	5. Removed STORE to default .priv or .shared.		5. Removed STORE to default .priv or .shared.
	skipping to change at page 19, line ? ¶		skipping to change at page 4, line 42 ¶
	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.
	This extension makes the following changes to the IMAP4 protocol:		This extension makes the following changes to the IMAP4 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 extension mechanism for adding parameters to the		f) adds a new requirement on the COPY command
			g) adds a extension mechanism for adding parameters to the
	SELECT/EXAMINE commands and defines the ANNOTATE parameter		SELECT/EXAMINE commands and defines the ANNOTATE parameter
	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 [ACAP]. Note that		of the Application Configuration Access Protocol [ACAP]. Note that
	there is no inheritance in annotations.		there is no inheritance in annotations.
	Clients MUST NOT use annotations in lieu of equivalent IMAP base		Clients MUST NOT use annotations in lieu of equivalent IMAP base
	specification facilities. For example, use of a "seen" flag in the		specification facilities. For example, use of a "seen" flag in the
	vendor namespace together with ".PEEK" in fetches. Such behaviour		vendor namespace together with ".PEEK" in fetches. Such behaviour
	would significantly reduce IMAP interoperability.		would significantly reduce IMAP interoperability.
	skipping to change at page 19, line ? ¶		skipping to change at page 6, line 40 ¶
	entire message. The "value" attribute of each of the entries		entire message. The "value" attribute of each of the entries
	described below must be either "1", "0" or NIL. "1" corresponds		described below must be either "1", "0" or NIL. "1" corresponds
	to the flag being set.		to the flag being set.
	/message/flags/answered		/message/flags/answered
	/message/flags/flagged		/message/flags/flagged
	/message/flags/deleted		/message/flags/deleted
	/message/flags/seen		/message/flags/seen
	/message/flags/draft		/message/flags/draft
	/message/flags/recent		/message/flags/recent
	These correspond to the standard IMAP flags.		These attributes represent the standard IMAP flags as returned
			by the FLAGS fetch item. Changes to these annotations are
			reflected in the standard IMAP flags. The recent attribute is
			read only, clients MUST NOT attempt to change it.
	/message/flags/redirected		/message/flags/redirected
	/message/flags/forwarded		/message/flags/forwarded
	The 'redirected' flag indicates that a message has been handed		The 'redirected' flag indicates that a message has been handed
	off to someone else, by resending the message with minimal		off to someone else, by resending the message with minimal
	alterations, and in such a way that a reply by the new recipient		alterations, and in such a way that a reply by the new recipient
	is addressed to the original author, not the user who performed		is addressed to the original author, not the user who performed
	the redirection. The 'forwarded' flag indicates the message was		the redirection. The 'forwarded' flag indicates the message was
	resent to another user, embedded within or attached to a new		resent to another user, embedded within or attached to a new
	message.		message.
	skipping to change at page 19, line ? ¶		skipping to change at page 7, line 39 ¶
	message as created by a particular product of some vendor.		message as created by a particular product of some vendor.
	These sub-entries can be used by vendors to provide		These sub-entries can be used by vendors to provide
	client-specific attributes. The vendor-token MUST be registered		client-specific attributes. The vendor-token MUST be registered
	with IANA.		with IANA.
	/body/<part-specifier>		/body/<part-specifier>
	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. This entry itself does not contain any		part of a message. This entry itself does not contain any
	attributes. The part-specifier uses the same part specifier		attributes. The part-specifier uses the same part specifier
	syntax as the BODY message data item in the FETCH command		syntax as the BODY message data item in the FETCH command
	[IMAP4].		[IMAP4]. The server MUST return a BAD response if the client
			uses an incorrect part specifier (either incorrect syntax or a
			specifier referring to a non-existent part). The server MUST
			return a BAD response if the client uses an empty part specifier
			(which is used in [IMAP4] to represent the entire message).
	/body/<part-specifier>/comment		/body/<part-specifier>/comment
	Defines a comment or note associated with a specific body part		Defines a comment or note associated with a specific body part
	of a message.		of a message.
	/body/<part-specifier>/flags		/body/<part-specifier>/flags
	Defines the top-level of entries associated with flag state for		Defines the top-level of entries associated with flag state for
	a specific body part of a message. All sub-entries are		a specific body part of a message. All sub-entries are
	maintained entirely by the client. There is no implicit change		maintained entirely by the client. There is no implicit change
	to any flag by the server.		to any flag by the server.
	skipping to change at page 19, line ? ¶		skipping to change at page 8, line 30 ¶
	approved experimental RFC, or fall under the vendor namespace. See		approved experimental RFC, or fall under the vendor namespace. See
	Section 10.1 for the registration template.		Section 10.1 for the registration template.
	All attribute names implicitly have a ".priv" and a ".shared" suffix		All attribute names implicitly have a ".priv" and a ".shared" suffix
	which maps to private and shared versions of the entry. Searching		which maps to private and shared versions of the entry. Searching
	or fetching without using either suffix includes both. The client		or fetching without using either suffix includes both. The client
	MUST specify either a ".priv" or ".shared" suffix when storing an		MUST specify either a ".priv" or ".shared" suffix when storing an
	annotation.		annotation.
	value		value
	The data value of the attribute.		A UTF8 string representing the data value of the attribute. To
			delete an annotation, the client can store NIL into the value.
	size		size
	The size of the value, in octets. Set automatically by the		The size of the value, in octets. Set automatically by the
	server, read-only to clients.		server, read-only to clients.
	content-type		content-type
	A MIME [MIME] content type and subtype that describes the nature		A MIME [MIME] content type and subtype that describes the nature
	of the content of the "value" attribute. If not present, a		of the content of the "value" attribute. If not present, a
	value of "text/plain; charset=utf8" is assumed.		value of "text/plain; charset=utf8" is assumed.
	skipping to change at page 19, line ? ¶		skipping to change at page 14, line 4 ¶
	S: a OK Store complete		S: a OK Store complete
	In the above example, the entry "/message/comment" is created (if		In the above example, the entry "/message/comment" is created (if
	not already present) and the private attribute "value" with data set		not already present) and the private attribute "value" with data set
	to "My new comment" is created if not already present, or replaced		to "My new comment" is created if not already present, or replaced
	if it exists.		if it exists.
	C: a STORE 1 ANNOTATION ("/message/comment"		C: a STORE 1 ANNOTATION ("/message/comment"
	("value.shared" NIL))		("value.shared" NIL))
	S: a OK Store complete		S: a OK Store complete
	In the above example, the shared "value" attribute of the entry		In the above example, the shared "value" attribute of the entry
	"/message/comment" is removed.		"/message/comment" is removed by storing NIL into the attribute.
	Multiple entries can be set in a single STORE command by listing		Multiple entries can be set in a single STORE command by listing
	entry-attribute-value pairs in the list.		entry-attribute-value pairs in the list.
	Example:		Example:
	C: a STORE 1 ANNOTATION ("/message/comment" ("value.priv"		C: a STORE 1 ANNOTATION ("/message/comment" ("value.priv"
	"Get tix Tuesday")		"Get tix Tuesday")
	"/message/subject" ("value.priv"		"/message/subject" ("value.priv"
	"Wots On"))		"Wots On"))
	S: a OK Store complete		S: a OK Store complete
	skipping to change at page 19, line ? ¶		skipping to change at page 14, line 36 ¶
	C: a STORE 1 ANNOTATION ("/message/comment"		C: a STORE 1 ANNOTATION ("/message/comment"
	("value.priv" "My new comment"		("value.priv" "My new comment"
	"vendor.foobar.priv" "foo's bar"))		"vendor.foobar.priv" "foo's bar"))
	S: a OK Store complete		S: a OK Store complete
	In the above example, the entry "/message/comment" is created (if		In the above example, the entry "/message/comment" is created (if
	not already present) and the private attributes "value" and		not already present) and the private attributes "value" and
	"vendor.foobar" are created if not already present, or replaced if		"vendor.foobar" are created if not already present, or replaced if
	they exist.		they exist.
	8.5 ANNOTATION Message Data Item in APPEND		8.5 ANNOTATION interaction with COPY
			The COPY command can be used to move messages from one mailbox to
			another on the same server. Servers that support the ANNOTATION
			extension MUST copy all the annotation data associated with any
			messages being copied via the COPY command. The only exception to
			this is if the destination mailbox permissions are such that either
			the '.priv' or '.shared' annotations are not allowed.
			8.6 ANNOTATION Message Data Item in APPEND
	ANNOTATION <parenthesised entry-attribute-value list>		ANNOTATION <parenthesised entry-attribute-value list>
	Sets the specified list of entries and attributes in the		Sets the specified list of entries and attributes in the
	resulting message.		resulting message.
	Example:		Example:
	C: a APPEND drafts ANNOTATION ("/message/comment"		C: a APPEND drafts ANNOTATION ("/message/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.
	8.6 ANNOTATION Criterion in SEARCH		8.7 ANNOTATION Criterion in SEARCH
	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.
	ANNOTATION <entry-name> <attribute-name> <value>		ANNOTATION <entry-name> <attribute-name> <value>
	Messages that have annotations with entries matching <entry-name>		Messages that have annotations with entries matching <entry-name>
	and attributes matching <attribute-name> and the specified string		and attributes matching <attribute-name> and the specified string
	<value> in their values are returned in the SEARCH results. The "*"		<value> in their values are returned in the SEARCH results. The "*"
	character can be used in the entry or attribute name fields to match		character can be used in the entry or attribute name fields to match
	skipping to change at page 19, line ? ¶		skipping to change at page 15, line 32 ¶
	<value> in their values are returned in the SEARCH results. The "*"		<value> in their values are returned in the SEARCH results. The "*"
	character can be used in the entry or attribute name fields to match		character can be used in the entry or attribute name fields to match
	any content in those items. The "%" character can be used in the		any content in those items. The "%" character can be used in the
	entry or attribute name fields to match a single level of hierarchy		entry or attribute name fields to match a single level of hierarchy
	only.		only.
	Examples:		Examples:
	C: a SEARCH ANNOTATION "/message/comment" "value" "IMAP4"		C: a SEARCH ANNOTATION "/message/comment" "value" "IMAP4"
	S: * SEARCH 2 3 5 7 11 13 17 19 23		S: * SEARCH 2 3 5 7 11 13 17 19 23
	S: a OK Search complete		S: a OK Search complete
	In the above example, the message numbers of any messages containing		In the above example, the message numbers of any messages containing
	the string "IMAP4" in the shared or private "value" attribute of the		the string "IMAP4" in the shared or private "value" attribute of the
	"/message/comment" entry are returned in the search results.		"/message/comment" entry are returned in the search results.
	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 containing		In the above example, the message numbers of any messages containing
	the string "IMAP4" in any attribute (public or private) of any entry		the string "IMAP4" in any attribute (public or private) of any entry
	are returned in the search results.		are returned in the search results.
	8.7 ANNOTATION Key in SORT		8.8 ANNOTATION Key in SORT
	The ANNOTATION criterion for the SORT command [SORT-EXT] instructs		The ANNOTATION criterion for the SORT command [SORT-EXT] instructs
	the server to return the message numbers or UIDs of a mailbox,		the server to return the message numbers or UIDs of a mailbox,
	sorted using the values of the specified annotations. The		sorted using the values of the specified annotations. The
	ANNOTATION criterion is available if the server returns both		ANNOTATION criterion is available if the server returns both
	"ANNOTATE" and "SORT" as supported capabilities in the CAPABILITY		"ANNOTATE" and "SORT" as supported capabilities in the CAPABILITY
	command response.		command response.
	ANNOTATION <entry-name> <attribute-name>		ANNOTATION <entry-name> <attribute-name>
	Messages are sorted using the values of the <attribute-name>		Messages are sorted using the values of the <attribute-name>
	attributes in the <entry-name> entries. (The charset argument		attributes in the <entry-name> entries. (The charset argument
	determines sort order, as specified in the SORT extension		determines sort order, as specified in the SORT extension
	description.)		description.)
	Examples:		Examples:
	C: a SORT (ANNOTATION "/message/subject" "value.shared") UTF-8		C: a SORT (ANNOTATION "/message/subject" "value.shared") UTF-8
	ALL		ALL
	skipping to change at page 19, line ? ¶		skipping to change at page 17, line 31 ¶
	; any character, excluding NUL		; any character, excluding NUL
	atom-slash = any utf8-char except "/"		atom-slash = any utf8-char except "/"
	atom-dot = any utf8-char except "."		atom-dot = any utf8-char except "."
	entry = DQUOTE 1*atom-slash *("/" 1*atom-slash) DQUOTE		entry = DQUOTE 1*atom-slash *("/" 1*atom-slash) DQUOTE
	entry-match = DQUOTE 1*entry-match-atom		entry-match = DQUOTE 1*entry-match-atom
	*("/" 1*entry-match-atom) DQUOTE		*("/" 1*entry-match-atom) DQUOTE
	entry-match-atom = 1*(list-wildcards / atom-slash)		entry-match-atom = 1*(list-wildcards / atom-slash)
	*(list-wildcards / atom-slash)		*(list-wildcards / atom-slash)
	attrib = DQUOTE 1*atom-dot *("/" 1*atom-dot) DQUOTE		attrib = DQUOTE 1*atom-dot *("." 1*atom-dot) DQUOTE
	attrib-match = DQUOTE 1*attrib-match-atom		attrib-match = DQUOTE 1*attrib-match-atom
	*("/" 1*attrib-match-atom) DQUOTE		*("." 1*attrib-match-atom) DQUOTE
	attrib-match-atom = 1*(list-wildcards / atom-dot)		attrib-match-atom = 1*(list-wildcards / atom-dot)
	*(list-wildcards / atom-dot)		*(list-wildcards / atom-dot)
	value = nstring		value = nstring
	select =/ *(SP "(" select-param *(SP select-param) ")"		select =/ *(SP "(" select-param *(SP select-param) ")"
	; modifies the original IMAP4 select command to		; modifies the original IMAP4 select command to
	; accept optional parameters		; accept optional parameters
	examine =/ *(SP "(" select-param *(SP select-param) ")"		examine =/ *(SP "(" select-param *(SP select-param) ")"
End of changes. 18 change blocks.
	26 lines changed or deleted		56 lines changed or added
This html diff was produced by rfcdiff 1.48. The latest version is available from http://tools.ietf.org/tools/rfcdiff/