IMAP Extensions Working Group C. Daboo Internet Draft: IMAP WINDOW Extension C. Newman Document: draft-ietf-imapext-window-00.txt June 2001 IMAP WINDOW Extension Status of this Memo This document is an Internet-Draft and is in full conformance with all provisions of Section 10 of RFC2026. 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. The list of Internet- Draft Shadow Directories can be accessed at http://www.ietf.org/shadow.html. Copyright Notice Copyright (C) The Internet Society (2001). All Rights Reserved. Daboo, Newman Expires December 2001 [Page 1]Internet Draft IMAP WINDOW Extension June 2001 Table of Contents 1 Abstract . . . . . . . . . . . . . . . . . . . . . . . . . . 2 2 Conventions Used in This Document . . . . . . . . . . . . . 2 3 Introduction and Overview . . . . . . . . . . . . . . . . . . 3 4 Open Issues . . . . . . . . . . . . . . . . . . . . . . . . 4 5 Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 5 5.1 Input Window . . . . . . . . . . . . . . . . . . . . . . 5 5.2 Output Results . . . . . . . . . . . . . . . . . . . . . 5 5.3 Output Position . . . . . . . . . . . . . . . . . . . . 5 5.4 Output Window . . . . . . . . . . . . . . . . . . . . . . 5 5.5 Anchor . . . . . . . . . . . . . . . . . . . . . . . . . 5 5.6 Anchor Offset . . . . . . . . . . . . . . . . . . . . . . 5 6 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . 5 7 Commands . . . . . . . . . . . . . . . . . . . . . . . . . . 6 7.1 WINDOW Command . . . . . . . . . . . . . . . . . . . . . 6 7.1.1 WINDOW SET . . . . . . . . . . . . . . . . . . . . . 6 7.1.2 WINDOW SHOW . . . . . . . . . . . . . . . . . . . . 7 7.1.3 WINDOW UPDATE . . . . . . . . . . . . . . . . . . . . 8 7.1.4 WINDOW MAP . . . . . . . . . . . . . . . . . . . . . 9 7.2 UID Command modifications . . . . . . . . . . . . . . . . 10 7.2.1 UID WINDOW SHOW . . . . . . . . . . . . . . . . . . 10 7.2.2 UID WINDOW MAP . . . . . . . . . . . . . . . . . . . 10 8 Responses . . . . . . . . . . . . . . . . . . . . . . . . . 10 8.1 WINDOW SET Untagged Response . . . . . . . . . . . . . . 10 8.2 WINDOW Untagged Response . . . . . . . . . . . . . . . . 10 8.3 WINDOW MAP Untagged Response . . . . . . . . . . . . . . 10 9 Handling message expunges . . . . . . . . . . . . . . . . . 10 10 Formal Syntax . . . . . . . . . . . . . . . . . . . . . . . . 11 11 Security Considerations . . . . . . . . . . . . . . . . . . 12 12 References . . . . . . . . . . . . . . . . . . . . . . . . . 12 13 Acknowledgments . . . . . . . . . . . . . . . . . . . . . . 12 14 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . 12 1 Abstract The WINDOW extension to the Internet Message Access Protocol [IMAP4] permits windowing of the results of specific IMAP commands, so that clients can retrieve the results in ranges to implement paging of results or virtual scrollbars. This eliminates the need to get and manage the entire result set, improving scalability for large mailboxes and slow connections. 2 Conventions Used in This Document The key words "REQUIRED", "MUST", "MUST NOT", "SHOULD", "SHOULD NOT", and "MAY" in this document are to be interpreted as described in "Key words for use in RFCs to Indicate Requirement Levels" [KEYWORDS]. Daboo, Newman Expires December 2001 [Page 2]Internet Draft IMAP WINDOW Extension June 2001 Formal syntax is defined using ABNF [ABNF]. In examples, "C:" and "S:" indicate lines sent by the client and server respectively. 3 Introduction and Overview The WINDOW extension is present in any IMAP4 implementation which returns "WINDOW" as one of the supported capabilities in the CAPABILITY command. The WINDOW extension specifies one new command (with a number of variants) and introduces one new untagged response (with a number of variants). The WINDOW command is an optimization for scalability purposes; clients can provide the same functionality, albeit more slowly, by using existing commands. The SEARCH [IMAP4], SORT [SORT] and THREAD [THREAD] commands in IMAP4 return a list of results equal to the size of the input window. The input window is determined by the parameters to each command. For example, the SEARCH command can limit its input window by using sequence number or UID number ranges as parameters to the SEARCH: Example: C: A999 SEARCH UNSEEN 10:20 S: * SEARCH 1 2 4 6 S: A999 OK SEARCH completed In the above example, an input window of messages with sequence numbers in the range 10 through 20 are the only ones considered by the SEARCH command. This limits the output to a maximum of 11 hits. The SORT and THREAD commands both take search criteria as parameters, and thus can also accomplish input windowing if desired. While input windowing can reduce the number of results returned, it does not offer a way to window the results based on their output ordering or size. The design goal of the WINDOW extension is to allow clients to do output windowing of the results of SEARCH and SORT commands, and to provide an extensible mechanism for future IMAP command extensions that return results as a list of sequence numbers or UIDs. In order to keep the WINDOW extension simple, the THREAD command is not included as one of the commands that WINDOW works with, due to the hierarchical nature of the THREAD command results. This extension makes the following changes to the IMAP4 protocol: Daboo, Newman Expires December 2001 [Page 3]Internet Draft IMAP WINDOW Extension June 2001 (a) Adds a new WINDOW command which takes one of four forms: (i) The first form, WINDOW SET, takes an optional sub-command and is used to initiate or cancel the windowing mechanism on the server. When initiating a window, the server creates an output results set consisting of all messages returned by the sub-command, in their appropriate ordering. The server returns the maximum size of the output results set as well as the position of the first unseen message in the output results set. (ii) The second form, WINDOW SHOW, takes parameters that allow the client to precisely specify the output window range. This command causes the server to return the message numbers for messages in this output window, which is a subset of the entire output results set. (iii) The third form, WINDOW UPDATE, causes the server to update the output results set to reflect any changes to the state of the mailbox since the last WINDOW SET <sub-command> command was issued. (iv) The fourth form, WINDOW MAP, the client provides a set of ordered message sequence numbers or UIDs and the server returns the output positions of those messages in the current output results set. For example, this allows a client to preserve user message selections across WINDOW UPDATEs or other mailbox changes. (b) Adds a new WINDOW untagged response which takes one of three forms: (i) The first form, WINDOW SET, returns the size and position of the first unseen message in the output results set. (ii) The second form, WINDOW, returns the output window range. (iii) The third form, WINDOW MAP, returns the mapping results from message sequence number or UIDs to output positions in the current output results set. (c) Modifies the EXPUNGE untagged response to include the output position of the message being expunged, when a WINDOW SET operation is in effect. The rest of this document describes these changes more rigorously. 4 Open Issues - Should we have WINDOW FETCH and WINDOW STORE commands to allow accessing messages by output position? Daboo, Newman Expires December 2001 [Page 4]Internet Draft IMAP WINDOW Extension June 2001 5 Terminology 5.1 Input Window The set of messages used as input to a SEARCH or SORT command. In the case of SEARCH this can be controlled via the message number or UID range search criteria. In the case of SORT this is controlled by the search criteria used with those commands. 5.2 Output Results The set of ordered message numbers or UIDs that are the results of a SEARCH or SORT command. 5.3 Output Position The position of a message in the output results, a number from 1 to <n> where <n> is the total number of messages in the output results. 5.4 Output Window A contiguous range of messages in the output results that the client wishes to know about. 5.5 Anchor A specific message that the client wants to appear at a particular position in the output window, requiring the server to determine the actual output window range to accommodate this requirement. For example, when first opening a mailbox, the client may want to position the first unseen message at the top of the list presented to the user by scrolling its graphical window to the appropriate place. 5.6 Anchor Offset The position of the anchor message in the output window, relative to the start or end of the output window. 6 Examples The examples below will all use the following output results set for consistency. There are a total of 20 messages in this set and the first unseen message in the set has a sequence number of 14 and appears at output position 3. Output results: 11 12 14 16 30 22 24 13 15 31 10 44 21 23 42 41 37 27 26 25 ^ first unseen message Daboo, Newman Expires December 2001 [Page 5]Internet Draft IMAP WINDOW Extension June 2001 The output results after an update. There are a total of 14 messages in this set and the first unseen message in the set has a sequence number of 22 and appears at output position 6. Output results after an update: 11 12 14 16 30 22 24 13 15 31 10 44 21 23 ^ first unseen message 7 Commands 7.1 WINDOW Command The WINDOW command is only available when the server is in 'selected state' [IMAP4]. Thus a successful SELECT or EXAMINE command MUST have been issued before WINDOW can be used. If a client attempts to use WINDOW while the server is not in 'selected state', then the server MUST respond with a BAD response. To avoid ambiguities when messages are expunged from the mailbox, the server MUST NOT send untagged EXPUNGE responses whilst a WINDOW command is in progress, The WINDOW command takes one of four forms. 7.1.1 WINDOW SET Arguments: OPTIONAL sub-command and associated arguments: this draft currently only allows the SEARCH and SORT [SORT] commands as the sub-commands. Responses: REQUIRED untagged responses: WINDOW SET Result: OK - window set completed, now in window state NO - window set failure BAD - command unknown or arguments invalid The WINDOW SET command is used to define the set of messages that form the output results. This set is determined by the result of the sub-command, and is ordered according to the sub-command. The server stores the output results, which are used to return the data the client may request using other WINDOW commands. The server MUST return an untagged WINDOW SET response to the WINDOW SET command, indicating the total number of messages in the output results, as well as the output position number of the first unseen message in the output results, or zero if there are no unseen messages in the output results. Example: C: A999 WINDOW SET SEARCH FROM "Smith" S: * WINDOW SET 20 3 Daboo, Newman Expires December 2001 [Page 6]Internet Draft IMAP WINDOW Extension June 2001 S: A999 OK WINDOW SET completed In this example an output results set on a SEARCH command is created. The output results have a total of 20 messages in it, and the first unseen message is at output position 3 in the output results. A WINDOW SET command with no arguments is used to cancel an earlier WINDOW SET with a sub-command. This allows a client to turn off the windowing behaviour. 7.1.2 WINDOW SHOW Arguments: the message number or starting position of the anchor message, the anchor position within the output window, the size of the output window to return. Responses: REQUIRED untagged responses: WINDOW Result: OK - window show completed NO - window show failure BAD - command unknown or arguments invalid The WINDOW SHOW command is used by the client to retrieve portions of the output results defined by an earlier WINDOW SET command. If the server is in selected state and there was no previous WINDOW SET command, or the WINDOW SET command was cancelled, then the server MUST respond with a BAD response. The WINDOW SHOW command takes three parameters: a) An identifier indicating the position of the anchor message in the output window. The client can specify the message by either its sequence number, uid or position in the output results set. This is done by using a single character before the numeric value to indicate what type it is: 'S' for sequence number, 'U' for uid and 'P' for output position. b) The requested anchor position where the anchor message should appear in the output window, relative to either the start or end of the output window. The server MUST return a BAD response if the requested anchor position exceeds the size of the output window, as specified in the third argument. c) The size of the output window. If the size provided by the client exceeds the size of the output results, the server MUST return a BAD response. The server MUST respond with an untagged WINDOW response indicating the output position of the first message in the output window range, followed by the message numbers of the messages in the range requested by the client. In some cases the anchor may not appear at Daboo, Newman Expires December 2001 [Page 7]Internet Draft IMAP WINDOW Extension June 2001 the relative offset in the output window requested by the client, because the offset would result in the output window exceeding the range of the output results. Example: C: A999 WINDOW SHOW P 3 +0 10 S: * WINDOW 3 14 16 30 22 24 13 15 31 10 44 S: A999 OK WINDOW SHOW completed In this example the client requests the server to return the message sequence numbers for 10 messages, anchored on output position 3 (the first unseen message), with the anchor set to appear first in the output window. The server responds with the output position of the first message in the output window range, followed by the 10 message sequence numbers corresponding to the requested messages - the message with sequence number 14 is the anchor and the first unseen message in the output results. Example: C: A999 WINDOW SHOW P 20 -0 10 S: * WINDOW 11 10 44 21 23 42 41 37 27 26 25 S: A999 OK WINDOW SHOW completed In this example the client requests the server to return the message sequence numbers for the last ten messages in the output results. This is accomplished by setting the anchor to the last output position, and requesting the anchor to appear last in the output window. Example: C: A999 WINDOW SHOW S 14 +5 10 S: * WINDOW 1 11 12 14 16 30 22 24 13 15 31 S: A999 OK WINDOW SHOW completed In this example the client requests an output window centered on the message with sequence number 14. However, that message actually appears at output position 3, so the specified anchor position cannot be accommodated, so the output window contains the anchor at position 3 instead of the requested position 5 from the start. 7.1.3 WINDOW UPDATE Arguments: None. Responses: REQUIRED untagged responses: WINDOW SET Result: OK - window update completed NO - window update failure BAD - command unknown The WINDOW UPDATE command is used to update the output results created by a previous WINDOW SET command. This is needed because WINDOW SET's output results are static - i.e. they do not change even when the state of messages changes, or new messages are added to the mailbox. In order to account for change to the mailbox, the Daboo, Newman Expires December 2001 [Page 8]Internet Draft IMAP WINDOW Extension June 2001 client must use the WINDOW UPDATE command. If the server is in selected state and there was no previous WINDOW SET command, or the WINDOW SET command was cancelled, then the server MUST respond with a BAD response. The server MUST return an untagged WINDOW SET response to the WINDOW SET command, indicating the total number of messages in the new output results, as well as the output position number of the first unseen message in the new output results, or zero if there are no unseen messages in the new output results. Example: C: A999 WINDOW UPDATE S: * WINDOW SET 14 6 S: A999 OK WINDOW UPDATE completed In this example the new output results have a total of 14 messages in it, and the first unseen message is now at output position 6 in the new output results. 7.1.4 WINDOW MAP Arguments: Message number range. Responses: REQUIRED untagged responses: WINDOW MAP Result: OK - window map completed NO - window map failure BAD - command unknown The WINDOW MAP command allows a client to determine the output positions of messages based on their sequence number or uid (if the UID command modifier is also used). This is required to help preserve a user's message selection state before and after a WINDOW UPDATE command is used. If the server is in selected state and there was no previous WINDOW SET command, or the WINDOW SET command was cancelled, then the server MUST respond with a BAD response. The server MUST return an untagged WINDOW MAP response to the WINDOW MAP command, indicating the new output positions of the requested messages, corresponding to the range used as the argument to the command. The server MUST return an output position number of zero for any messages that are no longer in the output results. If the message number argument specifies one or more messages that are not in the output results set, the server MUST respond with a BAD response. Example: C: A999 WINDOW MAP 5,14:16,22,24 S: * WINDOW MAP 0 3 9 4 5 6 S: A999 OK WINDOW MAP completed Daboo, Newman Expires December 2001 [Page 9]Internet Draft IMAP WINDOW Extension June 2001 In this example the client requests the output positions of messages with sequence numbers 5, 14, 15, 16, 22 and 24. Message 5 is not in the output results set, so its output position number is zero. 7.2 UID Command modifications The IMAP UID command is used to modify the meaning of another command and/or the untagged results of a command. The WINDOW extensions extends the UID command to accept certain WINDOW commands as outlined below. 7.2.1 UID WINDOW SHOW The UID WINDOW SHOW causes the untagged WINDOW response for the WINDOW SHOW command to contain message uids rather than message sequence numbers. 7.2.2 UID WINDOW MAP The UID WINDOW MAP causes the message number range argument to the WINDOW MAP command to be interpreted as message uids rather than message sequence numbers. 8 Responses 8.1 WINDOW SET Untagged Response The WINDOW SET untagged response is used to inform the client of the total number of messages in the output results set and the output position of the first unseen message in the output results, or zero if no unseen message is present in the output results. The WINDOW SET results can only occur as the result of a WINDOW SET or WINDOW UPDATE command. 8.2 WINDOW Untagged Response The WINDOW untagged response returns the output position of the first message in the requested output window, followed by the message numbers of the messages in the requested output window. The message numbers may be either sequence numbers or uids depending on whether the UID command modifier is used. The WINDOW response can only occur as the result of a WINDOW SHOW command. 8.3 WINDOW MAP Untagged Response The WINDOW MAP untagged response returns the output positions of messages in the output results, ordered according to the ordering of message numbers in the WINDOW MAP command. The WINDOW MAP response can only occur as the result of a WINDOW MAP command. Daboo, Newman Expires December 2001 [Page 10]Internet Draft IMAP WINDOW Extension June 2001 9 Handling message expunges When a WINDOW SET command is in effect, the server MUST modify any untagged EXPUNGE responses it sends to the client to include the output position of the message being expunged, or zero if the message being expunged is not in the output results. After each EXPUNGE response the output positions for the current WINDOW SET must be readjusted to account for the expunged message. When an untagged EXPUNGE response with a non-zero output position is seen by the client, the client MUST adjust its output window and output results state to take account of the expunged message. Example: C: A999 NOOP S: * 1 EXPUNGE 0 S: * 10 EXPUNGE 1 S: * 10 EXPUNGE 1 S: A999 OK In this example three messages are expunged from the mailbox. Message number 1 is not part of the previously determined output results so its output position is shown as zero. Message number 11 was at output position 1, and message number 12 was at output position number 1 after message number 11 was expunged. 10 Formal Syntax The following syntax specification uses the Augmented Backus-Naur Form (ABNF) notation as specified in [ABNF]. Non-terminals referenced but not defined below are as defined by [IMAP4]. 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. window-set-cmd = "WINDOW SET" SP window-set-arg window-set-arg = search / sort / OTHER ; search is defined in [IMAP4] ; sort is defined in [SORT] ; OTHER reserved for future definition window-update-cmd = "WINDOW UPDATE" window-set-resp = "*" SP "WINDOW SET" SP number SP number window-show-cmd = "WINDOW SHOW" SP anchor-pos SP anchor-rel SP nz-number Daboo, Newman Expires December 2001 [Page 11]Internet Draft IMAP WINDOW Extension June 2001 anchor-pos = ("S" / "U" / "P") SP nz-number ; "S" indicates sequence number ; "U" indicates uid ; "P" indicates output position anchor_rel = ("+" / "-") number ; "+" indicates offset from start ; "-" indicates offset from end window-resp = "*" SP "WINDOW" SP nz-number *(SP nz-number) window-map-cmd = "WINDOW MAP" SP set window-map-resp = "*" SP "WINDOW MAP" SP number *(SP number) message-data /= nz-number SP "EXPUNGE" SP number ; modifies [IMAP4] EXPUNGE response ; to return output position when ; WINDOW SET is in effect 11 Security Considerations There are no known security issues with this extension. 12 References [ABNF] Crocker, Overell, "Augmented BNF for Syntax Specifications: ABNF", RFC 2234, Internet Mail Consortium, Demon Internet Ltd, November 1997. [KEYWORDS] Bradner, "Key words for use in RFCs to Indicate Requirement Levels", RFC 2119, Harvard University, March 1997. [IMAP4] Crispin, M., "Internet Message Access Protocol - Version 4rev1", RFC 2060, University of Washington, December 1996. [SORT] Crispin, M., "Internet Message Access Protocol - SORT Extension", draft-ietf-imapext-sort-03.txt (Work in progress) [THREAD] Crispin, M., "Internet Message Access Protocol - THREAD Extension", draft-crispin-imapext-thread-01.txt (Work in progress) 13 Acknowledgments This work is the result of many discussions within the imap-ext working group, and is based on the original VIEW draft. Daboo, Newman Expires December 2001 [Page 12]Internet Draft IMAP WINDOW Extension June 2001 14 Authors' Addresses Cyrus Daboo Cyrusoft International, Inc. Suite 780, 5001 Baum Blvd. Pittsburgh, PA 15213 USA Email: daboo@cyrusoft.com Chris Newman Sun Microsystems 1050 Lakes Drive West Covina, CA 91790 USA Email: cnewman@iplanet.com Daboo, Newman Expires December 2001 [Page 13]
Datatracker
Report a datatracker bug
draft-ietf-imapext-window-00
None
| Document | Document type |
Expired Internet-Draft
(imapext WG)
Expired & archived
|
|
|---|---|---|---|
| Select version | |||
| Authors |
Cyrus Daboo
,
Chris Newman
Email authors |
||
| RFC stream |
|
||
| Intended RFC status | (None) | ||
| Other formats | |||
| Additional resources | Mailing list discussion |