idnits 2.17.1 draft-ietf-imapext-view-00.txt: ** The Abstract section seems to be numbered Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- ** Looks like you're using RFC 2026 boilerplate. This must be updated to follow RFC 3978/3979, as updated by RFC 4748. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- ** The document seems to lack a 1id_guidelines paragraph about Internet-Drafts being working documents. == No 'Intended status' indicated for this document; assuming Proposed Standard Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** The document seems to lack an IANA Considerations section. (See Section 2.2 of https://www.ietf.org/id-info/checklist for how to handle the case when there are no actions for IANA.) ** The document seems to lack separate sections for Informative/Normative References. All references will be assumed normative when checking for downward references. ** The abstract seems to contain references ([IMAP4]), which it shouldn't. Please replace those with straight textual mentions of the documents in question. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the RFC 3978 Section 5.4 Copyright Line does not match the current year == The document seems to lack the recommended RFC 2119 boilerplate, even if it appears to use RFC 2119 keywords. (The document does seem to have the reference to RFC 2119 which the ID-Checklist requires). -- The document seems to lack a disclaimer for pre-RFC5378 work, but may have content which was first submitted before 10 November 2008. If you have contacted all the original authors and they are all willing to grant the BCP78 rights to the IETF Trust, then this is fine, and you can ignore this comment. If not, you may need to add the pre-RFC5378 disclaimer. (See the Legal Provisions document at https://trustee.ietf.org/license-info for more information.) -- The document date (July 2000) is 8684 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) == Missing Reference: 'UNSEEN 12' is mentioned on line 715, but not defined == Missing Reference: 'UIDVALIDITY 3857529045' is mentioned on line 365, but not defined == Missing Reference: 'UIDNEXT 4392' is mentioned on line 366, but not defined == Missing Reference: 'UIDVALIDITY 3857429045' is mentioned on line 716, but not defined == Unused Reference: 'MIME-IMB' is defined on line 855, but no explicit reference was found in the text == Unused Reference: 'RFC-822' is defined on line 859, but no explicit reference was found in the text ** Obsolete normative reference: RFC 2234 (ref. 'ABNF') (Obsoleted by RFC 4234) ** Obsolete normative reference: RFC 2060 (ref. 'IMAP4') (Obsoleted by RFC 3501) ** Obsolete normative reference: RFC 822 (Obsoleted by RFC 2822) == Outdated reference: A later version (-20) exists of draft-ietf-imapext-sort-03 -- Possible downref: Normative reference to a draft: ref. 'THREAD' Summary: 9 errors (**), 0 flaws (~~), 10 warnings (==), 3 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 1 IMAP Extensions Working Group C. Daboo 2 Internet Draft: IMAP VIEW Extension M. Pustilnik 3 M. Crispin 4 Document: draft-ietf-imapext-view-00.txt July 2000 6 IMAP VIEW Extension 8 Status of this Memo 10 This document is an Internet-Draft and is in full conformance with 11 all provisions of Section 10 of RFC2026. Internet-Drafts are 12 working documents of the Internet Engineering Task Force (IETF), its 13 areas, and its working groups. Note that other groups may also 14 distribute working documents as Internet-Drafts. 16 Internet-Drafts are draft documents valid for a maximum of six 17 months and may be updated, replaced, or obsoleted by other documents 18 at any time. It is inappropriate to use Internet-Drafts as 19 reference material or to cite them other than as "work in progress." 21 The list of current Internet-Drafts can be accessed at 22 http://www.ietf.org/ietf/1id-abstracts.txt. The list of Internet- 23 Draft Shadow Directories can be accessed at 24 http://www.ietf.org/shadow.html. 26 Copyright Notice 28 Copyright (C) The Internet Society (2000). All Rights Reserved. 30 Table of Contents 31 1 Abstract . . . . . . . . . . . . . . . . . . . . . . . . . . 2 32 2 Conventions Used in This Document . . . . . . . . . . . . . 2 33 3 Introduction and Overview . . . . . . . . . . . . . . . . . . 3 34 4 Commands . . . . . . . . . . . . . . . . . . . . . . . . . . 4 35 4.1 VIEW Command . . . . . . . . . . . . . . . . . . . . . . 5 36 4.1.1 VIEW SET . . . . . . . . . . . . . . . . . . . . . . 5 37 4.1.2 VIEW . . . . . . . . . . . . . . . . . 6 38 4.2 Modified SELECT and EXAMINE commands . . . . . . . . . . 8 39 5 Responses . . . . . . . . . . . . . . . . . . . . . . . . . . 8 40 5.1 Response Conditions . . . . . . . . . . . . . . . . . . 8 41 5.2 Server Modes . . . . . . . . . . . . . . . . . . . . . . 9 42 5.3 New Message Arrival Processing . . . . . . . . . . . . . 9 43 5.4 Examples of use of the \View Flag . . . . . . . . . . . . 10 44 5.4.1 Dynamic . . . . . . . . . . . . . . . . . . . . . . 10 45 5.4.2 Semi-dynamic . . . . . . . . . . . . . . . . . . . . 11 46 5.4.3 Static . . . . . . . . . . . . . . . . . . . . . . . 11 47 5.5 VIEW Untagged Response . . . . . . . . . . . . . . . . . 12 48 5.5.1 New message arrival . . . . . . . . . . . . . . . . 12 49 5.5.2 Messages moving in the view . . . . . . . . . . . . . 13 50 5.5.3 VIEW SEARCH Response . . . . . . . . . . . . . . . . 14 51 5.6 EXISTS Untagged Response . . . . . . . . . . . . . . . . 15 52 5.7 EXPUNGE Untagged Response . . . . . . . . . . . . . . . 15 53 6 Formal Syntax . . . . . . . . . . . . . . . . . . . . . . . . 16 54 7 Security Considerations . . . . . . . . . . . . . . . . . . 17 55 8 References . . . . . . . . . . . . . . . . . . . . . . . . . 17 56 9 Acknowledgments . . . . . . . . . . . . . . . . . . . . . . 18 57 10 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . 18 59 1 Abstract 61 The VIEW extension to the Internet Message Access Protocol [IMAP4] 62 permits a subset of messages in the mailbox to be processed 63 separately from the entire set of messages in the mailbox. This 64 allows a client to restrict its view to only the messages appearing 65 in this set. The subset of messages also need not be returned in 66 order of their sequence numbers, allowing clients to access messages 67 in a particular sort order. 69 The subsetting and sorting of messages is handled by existing 70 [IMAP4] commands that return a set of messages as their result. 71 This extension takes the set returned from such a command and 72 applies the VIEW methodology to it. 74 2 Conventions Used in This Document 76 The key words "REQUIRED", "MUST", "MUST NOT", "SHOULD", "SHOULD 77 NOT", and "MAY" in this document are to be interpreted as described 78 in "Key words for use in RFCs to Indicate Requirement Levels" 79 [KEYWORDS]. 81 Formal syntax is defined using ABNF [ABNF]. 83 In examples, "C:" and "S:" indicate lines sent by the client and 84 server respectively. 86 3 Introduction and Overview 88 The VIEW extension is present in any IMAP4 implementation which 89 returns "VIEW" as one of the supported capabilities in the 90 CAPABILITY command. 92 The VIEW extension specifies one new command and introduces one new 93 untagged response, modifies two existing [IMAP4] commands and two 94 existing [IMAP4] untagged responses, as well as putting requirements 95 on standard IMAP4 protocol responses when the command is in effect. 96 It also introduces a new message flag. 98 Each of the features in VIEW are optimizations; clients can provide 99 the same functionality, albeit more slowly, by using existing 100 commands. 102 The design goal of the VIEW extension is to allow clients to 103 reference messages only by their "view position numbers" as opposed 104 to sequence numbers or UIDs, if so desired, and thus remove the need 105 for the client to maintain its own mapping between sequence number, 106 UID and view position. 108 This extension makes the following changes to the IMAP4 protocol: 110 (a) Adds a new VIEW command which takes one of two forms: 112 (i) The first form, VIEW SET, takes an optional sub-command and 113 is used to initiate or cancel the view mechanism on the server. 115 (ii) In the second form, the VIEW command is used with a FETCH, 116 COPY, STORE or SEARCH command, and instructs the server to 117 interpret the sequence numbers provided by the client in the 118 command as VIEW positions (as described below), or to return 119 results using view positions rather than sequence numbers. The 120 VIEW COPY command also requires that messages be copied in view 121 order into the destination mailbox. 123 (b) Allows the arguments of the VIEW SET command to appear as 124 arguments of the SELECT or EXAMINE commands [IMAP4] to allow 125 selecting a mailbox and setting a view in a single round-trip. 127 When the VIEW SET command is used by the client, the following 128 changes also take place: 130 (c) New FETCH message data response item: 132 VIEW 133 Indicates the position of messages in the view, which may be 134 different from message sequence number. 136 (d) New untagged response: 138 VIEW 139 Indicates new message arrival, a change in position of a 140 message within the current view or a message moving in or 141 out of the current view. The sequence number, UID and new 142 view position number of the message are supplied, and 143 optionally the old position when the message is not new. 144 Can also be used to return SEARCH results using view 145 position numbers rather than sequence numbers or UIDs. 147 (e) Changes to untagged responses and response codes: 149 EXISTS 150 The standard EXISTS response is enhanced to include 151 information about the total number of messages in the 152 current view. 154 EXPUNGE 155 The standard EXPUNGE response is enhanced to include 156 information about message UID and view position. 158 (f) New message flag: 160 \View 161 The \View message flag is used to help clients create views 162 that contain specific messages that it wants. This allows 163 clients to implement a 'static' or 'semi-dynamic' view (as 164 described in the Section 5.2). The \View flag is only 165 present when a VIEW is in effect. This flag is a 'session' 166 flag. Its state must be maintained by the server separately 167 for each connection. 169 (g) New search criteria: 171 VIEW UNVIEW 172 The VIEW search criterion matches any message that has the 173 \View flag set. The UNVIEW search criterion matches any 174 message that does not have the \View flag set. These search 175 criteria are only present when a VIEW is in effect. 177 The rest of this document describes these changes more rigorously. 178 The document will use the IMAP4 SEARCH command as an example of a 179 sub-command to VIEW SET. However, other commands can be used with 180 VIEW SET as well. 182 4 Commands 184 4.1 VIEW Command 186 The VIEW command takes one of two forms. 188 4.1.1 VIEW SET 190 Arguments: OPTIONAL sub-command and associated arguments: 191 this draft currently only allows the SEARCH command 192 as the sub-command, however, anticipated SORT [SORT] 193 and THREAD [THREAD] commands are expected to be 194 added to this. 196 Responses: REQUIRED untagged responses: modified EXISTS if 197 sub-command present 199 Result: OK - view completed, now in view state 200 NO - view failure 201 BAD - command unknown or arguments invalid 203 The VIEW SET command is only available when the server is in 204 'selected state' [IMAP4]. Thus a successful SELECT or EXAMINE 205 command MUST have been issued before VIEW SET can be used. If a 206 client attempts to use VIEW SET while the server is not in 'selected 207 state', then the server MUST respond with a BAD response. Note that 208 a view can also be initiated by a SELECT or EXAMINE command, as 209 described in Section 4.2. 211 When the VIEW SET command is in effect (either by an explicit VIEW 212 SET command or by a modified SELECT or EXAMINE command), it results 213 in the following changes to the IMAP4 protocol: 215 (a) The server creates a 'view' that is a subset of messages in the 216 mailbox that match the results of the sub-command. The position 217 of a message in the view, its view position number, is then 218 given by the VIEW fetch item response. Messages outside of the 219 view have a view position of 0 (zero). 221 (b) The server MUST set the \View message flag on all messages 222 appearing in the view and remove the \View message flag from all 223 messages that are outside the view. Note that the server MUST 224 NOT send unsolicited FETCH responses to indicate the change in 225 \View flag state of any messages. 227 (c) The VIEW command can be used by the client to request 228 information about messages in the current view set, without 229 requiring the client to determine the view positions of every 230 message in the mailbox (see Section 4.1.2). 232 (d) The server MUST return a VIEW fetch item in every FETCH 233 response, including unsolicited FETCH responses. This ensures 234 the client does not need to maintain its own mapping from 235 sequence numbers to view positions. 237 (e) A new VIEW untagged response MUST be sent by the server when 238 changes are made to the view by the arrival of new messages, the 239 removal of messages, and the change in status of messages. The 240 rules governing when these responses are issued are described in 241 more detail in Section 5.1. 243 (f) The server MUST modify the EXISTS untagged response (see Section 244 5.6) to include additional information to indicate the current 245 number of messages in the view set. 247 (g) The server MUST modify the EXPUNGE untagged response (see 248 Section 5.7) to include additional information to indicate the 249 expunged message's UID and view position number. 251 (h) The VIEW SET command with no sub-command can be used to turn off 252 the view facility and return the server to standard IMAP4 253 behaviour. The server MUST NOT send unsolicited FETCH responses 254 to indicate removal of the \View flag for messages previously in 255 the VIEW. Once the view has been turned off, the \View flag is 256 not available. 258 (i) A VIEW SET command with a sub-command (see Section 4.1.2) can be 259 used while another VIEW SET is in effect. This results in the 260 view being 'reset' to use the new VIEW SET parameters. The 261 server MUST set the \View message flag on all messages appearing 262 in the new view and remove the \View message flag from all 263 messages that are outside the new view. Note that the server 264 MUST NOT send unsolicited FETCH responses to indicate the change 265 in \View flag state of any messages. 267 (j) Any SELECT, EXAMINE or CLOSE command issued while a VIEW SET is 268 in effect has the behaviour of canceling the current view and 269 returns the server to standard [IMAP4] behaviour, unless the 270 SELECT or EXAMINE commands include new VIEW SET arguments as 271 described in Section 4.2. The server MUST NOT send unsolicited 272 FETCH responses to indicate any change of the \View flag. If 273 the view has been turned off, the \View flag is not available. 275 Examples: 276 C: A999 VIEW SET SEARCH FROM "Smith" 277 S: * 23 EXISTS 5 278 S: A999 OK VIEW SET completed 280 4.1.2 VIEW 282 Arguments: command name 283 command arguments 284 Responses: untagged responses: FETCH, VIEW SEARCH 286 Result: OK - VIEW command completed 287 NO - VIEW command error 288 BAD - command unknown or arguments invalid 290 This version of the VIEW command is only available when the VIEW SET 291 command is in effect. Clients MUST NOT issue this version of the 292 VIEW command when a VIEW SET is not in effect, and servers MUST 293 respond with a tagged BAD response if it receives a VIEW command of 294 this type when VIEW SET is not in effect. This version of the VIEW 295 command has two forms. 297 In the first form, it takes as its arguments a COPY, FETCH, or STORE 298 command [IMAP4] with arguments appropriate for the associated 299 command. However, the numbers in the message set argument are view 300 position numbers instead of message sequence numbers. 302 When the VIEW COPY form is used, the server MUST copy messages into 303 the destination mailbox in the order they appear in the current 304 view. This may be different from the ordering of the view position 305 numbers provided as the argument to the VIEW COPY command. 307 In the second form, the VIEW command takes a SEARCH command with 308 SEARCH command arguments [IMAP4]. The interpretation of the 309 arguments is the same as with SEARCH [IMAP4]; however, the numbers 310 returned in a VIEW SEARCH response (see Section 5.5.3) for a VIEW 311 SEARCH command are view position numbers instead of message sequence 312 numbers. In addition, the search is carried out only on those 313 messages in the current view set, so a view position of 0 (zero) 314 MUST NOT be returned in the search results. 316 Example: 317 C: A999 VIEW SEARCH UNSEEN 318 S: * VIEW SEARCH 1 2 4 6 319 S: A999 OK VIEW SEARCH completed 321 When a FETCH response [IMAP4] is returned by the server when the 322 VIEW SET command is in effect, the number after the "*" in an 323 untagged FETCH response is always a message sequence number, not a 324 view position number, even for a response to any of the above VIEW 325 commands. However, server implementations MUST implicitly include 326 the VIEW fetch item as part of any FETCH response caused by a VIEW 327 command, regardless of whether a VIEW was specified as a message 328 data item to any FETCH, as described in Section 4.1.1 (c). 330 Example: 331 C: A999 VIEW FETCH 1:3 FLAGS 332 S: * 23 FETCH (FLAGS (\Seen) VIEW 2) 333 S: * 24 FETCH (FLAGS (\Seen) VIEW 3) 334 S: * 25 FETCH (FLAGS (\Seen) VIEW 1) 335 S: A999 OK VIEW FETCH completed 336 4.2 Modified SELECT and EXAMINE commands 338 This extension modifies the syntax of the existing IMAP4 SELECT and 339 EXAMINE commands as follows. 341 Arguments: mailbox name 342 OPTIONAL view set arguments 344 Response: same as [IMAP4] except for modified EXISTS 346 Result: same as [IMAP4] 348 The IMAP4 SELECT and EXAMINE commands are modified to include 349 optional VIEW SET command arguments after the mailbox name. This 350 allows a client to select a mailbox and set a view in a single 351 command. The syntax for the optional arguments are the same as for 352 the VIEW SET command arguments, and the behaviour following such a 353 command is as described in Section 4.1.1. 355 When the optional VIEW SET command arguments are present, the EXISTS 356 response that is normally sent by the server as part of the SELECT 357 or EXAMINE command response is modified to include the current 358 number of messages in the view, as described in Section 4.1.1 (f). 360 Examples: 361 C: A142 SELECT INBOX SEARCH FROM "Smith" 362 S: * 172 EXISTS 5 363 S: * 1 RECENT 364 S: * OK [UNSEEN 12] Message 12 is first unseen 365 S: * OK [UIDVALIDITY 3857529045] UIDs valid 366 S: * OK [UIDNEXT 4392] Predicted next UID 367 S: * FLAGS (\Answered \Flagged \Deleted \Seen \Draft) 368 S: * OK [PERMANENTFLAGS (\Deleted \Seen \*)] Limited 369 S: A142 OK [READ-WRITE] SELECT with VIEW SET completed 371 5 Responses 373 5.1 Response Conditions 375 There are a number of conditions that can give rise to changes in 376 the state of a mailbox when a VIEW SET command is in effect: 378 (a) New messages arriving in the mailbox that also match the current 379 view criteria 381 (b) New messages arriving in the mailbox that do not match the 382 current view criteria 384 (c) Messages removed from the mailbox (via EXPUNGE) that also match 385 the current view criteria 386 (d) Messages removed from the mailbox (via EXPUNGE) that do not 387 match the current view criteria 389 (e) Messages that do not match the current view criteria, but whose 390 state changes (e.g. a change in the message FLAGS) such that 391 they now match the current view criteria 393 (f) Messages that match the current view criteria, but whose state 394 changes (e.g. a change in the message FLAGS) such that they no 395 longer match the current view criteria 397 (g) Messages that match the current view criteria, but whose state 398 changes (e.g. a change in the message FLAGS) resulting in a 399 change to their view position, whilst still matching the current 400 view criteria 402 When VIEW SET is in effect, a server MUST always send untagged 403 responses for all the above response conditions to satisfy the 404 dynamic view mode behaviour described next. 406 5.2 Server Modes 408 There are three different modes that a view could operate in: 409 dynamic, semi-dynamic or static. Depending on the mode, the server 410 response conditions described above, may or may not be sent, as 411 determined by the following table: 413 +--------------------+-------------+--------------+-------------+ 414 | Response condition | Dynamic | Semi-dynamic | Static | 415 +====================|==========================================+ 416 | (a) (b) | Yes | Yes | No | 417 +--------------------|-------------+--------------+-------------+ 418 | (c) (d) | Yes | Yes | Yes | 419 +--------------------|-------------+--------------+-------------+ 420 | (e) (f) (g) | Yes | No | No | 421 +--------------------+-------------+--------------+-------------+ 423 Clients may want to operate in any of these modes, whereas for 424 simplicity, servers should only have to operate in one mode. 425 Therefore there needs to be a way to 'simulate' client modes given a 426 single server mode. 428 This specification adopts the dynamic mode of operation for the 429 server. Thus the server sends view update responses for all the 430 response conditions listed in Section 5.1. To simulate semi-dynamic 431 and static modes, a new message flag \View is introduced that allows 432 messages to be marked as belonging to the current view. This flag 433 is automatically set by the server when a message is added to the 434 view, but only the client can remove it. Examples of the use of 435 this flag in simulating different view modes are given Section 436 5.4. 438 5.3 New Message Arrival Processing 440 A special case exists for processing of new messages arriving in a 441 mailbox. To determine whether new messages match the current view 442 criteria the server must follow these rules: 444 i) If the view criteria does not include any criterion for the \View 445 flag, then the new message is considered to be in the view if it 446 matches the view criteria. If a new message is added to the 447 view, the server MUST set the \View flag for that message, but 448 MUST NOT send an unsolicited FETCH response to indicate the 449 change in \View flag state. 451 ii) If the view criteria contains any criterion for the \View flag, 452 the following procedure must be followed: the server should test 453 the message against the view criteria for the two cases where 454 the \View flag is set and not set. Based on the results of 455 these tests, the message may be added to the view with the \View 456 flag either set or not set: 458 +--------------+--------------+----------------------------+ 459 | Test without | Test with | Result | 460 | \View | \View |----------------------------| 461 | | | Add to VIEW | \View flag | 462 +==========================================================+ 463 | | | | | 464 | false | false | No | Not set | 465 | | | | | 466 +--------------+--------------+--------------+-------------+ 467 | | | | | 468 | false | true | Yes | Set | 469 | | | | | 470 +--------------+--------------+--------------+-------------+ 471 | | | | | 472 | true | false | Yes | Not set | 473 | | | | | 474 +--------------+--------------+--------------+-------------+ 475 | | | | | 476 | true | true | Yes | Set | 477 | | | | | 478 +--------------+--------------+--------------+-------------+ 480 5.4 Examples of use of the \View Flag 482 5.4.1 Dynamic 484 A typical scenario is that the user wants to display only 'new' 485 messages in a particular mailbox and read those messages. A VIEW 486 command to trigger this behaviour would be: 488 C: A001 VIEW SET SEARCH UNSEEN 489 This generates a dynamic view that shows only unseen messages. As 490 soon as a message has the \Seen flag set, it drops out of the view. 491 New messages arriving in the mailbox without the \Seen flag set are 492 automatically added to the view. 494 Another example is a view that 'hides' deleted messages 495 automatically. The VIEW command to trigger this would be: 497 C: A001 VIEW SET SEARCH UNDELETED 499 This generates a dynamic view containing only undeleted messages. 500 As soon as a message in the view is deleted, it drops out of the 501 view. 503 5.4.2 Semi-dynamic 505 In the first dynamic example above, as soon as the user reads a 506 message, it would drop out of the view as its \Seen flag would 507 likely be set. This can lead to undesired view updating in the 508 client as the message the user is working with suddenly 'disappears' 509 from their view. A better solution is to use a semi-dynamic mode 510 whereby the view shows initially unseen messages, but those messages 511 remain in the view once they are marked as seen. New messages 512 arriving in the mailbox without the \Seen flag set, will be 513 automatically added to the view. The VIEW command to trigger this 514 behaviour would be: 516 C: A001 VIEW SET SEARCH OR UNSEEN VIEW 518 By adding the VIEW search criteria, any messages initially appearing 519 in the view will remain in the view because they have their \View 520 flag set automatically. Following the rules described in Section 521 5.3, new messages arriving in the mailbox without the \Seen flag set 522 would automatically be added to the view by the server, which would 523 also set the \View flag on those messages. 525 A client can 'refresh' the semi-dynamic view to remove messages that 526 don't match the search criteria, other than having their \View flag 527 set, by re-issuing the original view command. 529 Clients may want to combine dynamic and semi-dynamic behaviours. 530 For example, a semi-dynamic 'unseen messages only' view with a 531 dynamic 'hide deleted messages' view. This could be accomplished 532 with the following VIEW command: 534 C: A001 VIEW SET SEARCH (OR UNSEEN VIEW) UNDELETED 536 5.4.3 Static 538 Clients can create static view using: 540 C: A001 VIEW SET SEARCH VIEW 541 This creates a view that initially has no contents. Clients can 542 then manage the contents of the view by setting or removing the 543 \View flag for messages in the mailbox. Setting the \View flag will 544 add a message to the view, removing the \View flag will remove a 545 message from the view. New messages are not automatically added to 546 the view, but messages expunged from the mailbox will be removed 547 from the view if they have their \View flag set. 549 5.5 VIEW Untagged Response 551 The VIEW untagged response is used to inform the client of changes 552 to the current view. This includes new messages appearing in the 553 view, messages being removed from the view, and messages changing 554 position inside the view. 556 5.5.1 New message arrival 558 VIEW 560 indicates that a new message has arrived with the given sequence 561 number, UID and view position number 563 When using the VIEW SET command, the VIEW untagged response augments 564 the EXISTS untagged response as a means of new mail notification. 565 Specifically it is used to tell the client where new messages appear 566 in the current view. The server MUST send an untagged VIEW response 567 for every new message that arrives in the mailbox, after the 568 corresponding untagged EXISTS response is sent to indicate this, 569 when the VIEW SET command is in effect. 571 When the VIEW SET command is in effect, and the view position number 572 of a new message is non-zero (i.e. the new message appears in the 573 current view), the untagged VIEW response causes the view position 574 numbers of all subsequent messages in the mailbox's current view to 575 be incremented. This corresponds to response condition (a) 576 described in Section 5.1. 578 Example: 580 C: NOOP 581 S: * 173 EXISTS 24 582 S: * 1 RECENT 583 S: * 173 VIEW 5274234 14 584 S: NOOP complete 586 indicates that a new message with sequence number 173 and UID 587 5274234 has been inserted into the view with view position 588 number 14. Any message that used to have a view position number 589 14 is now at position 15, etc. 591 If a new message arrives outside the current view (i.e. not matching 592 the specified search criteria), the view position number of the new 593 message is given as 0. This corresponds to response condition (b) 594 described in Section 5.1. 596 Example: 598 C: NOOP 599 S: * 174 EXISTS 24 600 S: * 2 RECENT 601 S: * 174 VIEW 5274235 0 602 S: NOOP complete 604 indicates that a message has arrived with sequence number 174 605 and UID 5274235, however, the VIEW SET command in effect 606 prevents it from being in the current view. 608 5.5.2 Messages moving in the view 610 VIEW 612 indicates that a message with the given sequence number and UID 613 has changed its position within the view 615 Some sub-commands of the VIEW SET command may change the sort order 616 of messages in the view. In such a case, changes to message flags 617 or keywords can cause the position of messages in sorted order to 618 change. Also, when search criteria are specified, changes to 619 message flags or keywords can cause messages to move into or outside 620 of the view. The server MUST communicate these changes to the 621 client by sending it the VIEW untagged response 623 When VIEW SET search criteria are in effect, changes made to a 624 message can cause it to drop out of view or, on the contrary, become 625 visible. When a message drops out of view, the new view position 626 number is sent as 0. Similarly, when a message appears in view, for 627 example, as a result of another agent changing the message 628 attributes, the old view position number is sent as 0. 630 When the old view position number in the VIEW untagged response is 631 0, the effect of VIEW is a message inserted into the view at the 632 position given by . The view position numbers of all 633 subsequent messages in the current view are implicitly incremented. 634 This corresponds to response condition (e) described in Section 635 5.1. 637 When the new view position number in the VIEW untagged response is 638 0, the effect of VIEW is a message removed from the view at the 639 position given by . The view position numbers of all 640 subsequent messages in the current view are implicitly decremented. 641 This corresponds to response condition (f) described in Section 642 5.1. 644 When both the and view positions are non-zero, then the 645 view positions of messages between the and positions 646 need to be implicitly decremented or incremented depending on 647 whether the view position is less than or greater than the 648 view position, respectively. This corresponds to response 649 condition (g) described in Section 5.1. 651 It is meaningless to have a VIEW untagged response where both 652 and view position numbers are 0; the server MUST NOT generate 653 VIEW responses of this form. 655 VIEW untagged responses indicating messages moving in the view MUST 656 NOT be sent as the result of messages being expunged (which is 657 handled by the modified untagged EXPUNGE response), or when no 658 command is in progress, or while responding to a FETCH, SEARCH or 659 STORE command. These rules are necessary to prevent loss of 660 synchronization of message sequence numbers between client and 661 server. 663 Examples: 665 S: * 172 VIEW 5274234 2 14 667 indicates that the view position of the message with sequence 668 number 172 and UID equal to 5274234 has changed from 14 to 2. 669 The view position numbers of the messages in the range 2:13 are 670 incremented. 672 S: * 172 VIEW 5274234 0 14 674 indicates that the message with view position number 14 has 675 dropped out of view. The view position numbers of subsequent 676 messages are decremented. The message continues to exist, 677 however, it is outside of the current view and is therefore no 678 longer accessible to the session via the VIEW command. 680 S: * 173 VIEW 5274234 2 0 682 indicates that the message with UID 5274234 has appeared in the 683 current view and has been assigned view position number 2. The 684 view position numbers of subsequent messages are incremented. 686 5.5.3 VIEW SEARCH Response 688 VIEW SEARCH 690 The VIEW SEARCH response occurs as a result of a VIEW SEARCH 691 command. The view position number(s) refer to those messages that 692 match the search criteria. Each number is delimited by a space. 694 Example: S: * VIEW SEARCH 2 3 6 696 5.6 EXISTS Untagged Response 698 <# in mailbox> EXISTS <# in view> 700 indicates the total number of messages in the mailbox and in the 701 current view 703 The modified EXISTS untagged response MUST only be used when the 704 VIEW SET command is in effect. This MUST be sent in response to a 705 VIEW SET command taking a sub-command argument. Otherwise this 706 response is sent under the same circumstances as the unmodified 707 EXISTS response (i.e. in when there is a change to the total number 708 of messages in the mailbox). 710 Example: 712 C: A142 SELECT INBOX 713 S: * 172 EXISTS 714 S: * 3 RECENT 715 S: * OK [UNSEEN 12] Message 12 is first unseen 716 S: * OK [UIDVALIDITY 3857429045] UIDs valid 717 S: * FLAGS (\Answered \Flagged \Deleted \Seen \Draft) 718 S: OK [PERMANENTFLAGS (\Deleted \Seen \*)] Limited 719 S: A142 OK [READ-WRITE] SELECT completed 720 C: A143 VIEW SET SEARCH FROM "Smith" 721 S: * 172 EXISTS 23 722 S: A143 OK VIEW SET completed 724 In this example, there are 172 messages in the mailbox and 23 725 messages have a from address including the text "Smith". 727 5.7 EXPUNGE Untagged Response 729 EXPUNGE 731 indicates that a message with given sequence number, UID and 732 view position number has been permanently removed from the 733 mailbox 735 When VIEW SET is in effect, the EXPUNGE untagged response [IMAP4] is 736 modified to include the UID and view position number of the message 737 being expunged. The server MUST use this modified form of the 738 EXPUNGE response whenever a VIEW SET command is in effect. 740 When the view position number of the expunged message is non-zero, 741 the modified EXPUNGE untagged response causes the view position 742 numbers of all subsequent messages in the mailbox's current view to 743 be decremented. This corresponds to response condition (c) 744 described in Section 5.1. 746 When search criteria are specified in the VIEW SET command, and a 747 message outside the current view is expunged, the view position 748 number of the expunged message is given as 0. This corresponds to 749 response condition (d) described in Section 5.1. 751 Examples: 753 S: * 172 EXPUNGE 5274234 14 755 indicates that the message with sequence number 172, UID 5274234 756 and view position number 14 has been expunged from its mailbox. 757 Any message previously at position 15 is now at position 14, etc 759 S: * 173 EXPUNGE 5274234 0 761 indicates that a message with sequence number 173, UID 5274234 762 was expunged, however, the message was outside the current view. 764 A modified EXPUNGE untagged response MUST NOT be sent when no 765 command is in progress; nor while responding to a FETCH, SEARCH or 766 STORE command. This rule is necessary to prevent loss of 767 synchronization of message sequence numbers between client and 768 server. 770 6 Formal Syntax 772 The following syntax specification uses the Augmented Backus-Naur 773 Form (ABNF) notation as specified in [ABNF]. 775 Non-terminals referenced but not defined below are as defined by 776 [IMAP4]. 778 Except as noted otherwise, all alphabetic characters are case- 779 insensitive. The use of upper or lower case characters to define 780 token strings is for editorial clarity only. Implementations MUST 781 accept these strings in a case-insensitive fashion. 783 examine = "EXAMINE" SP mailbox [SP view-set-arg] 784 ; redefines [IMAP4] EXAMINE command 786 exists_resp = number "EXISTS" SP number 787 ; replaces standard [IMAP4] EXISTS response 788 ; when VIEW SET is in effect 790 expunge_resp = nz-number "EXPUNGE" SP uniqueid SP position 791 ; replaces standard IMAP4 EXPUNGE response 792 ; when VIEW SET is in effect 794 flag =/ "\View" 795 ; extends [IMAP4] message flags 796 ; new flag is only available when 797 ; VIEW SET is in effect 799 msg-att-dynamic =/ "VIEW" SP position 800 ; extends [IMAP4] message data item 801 ; FETCH response 803 position = number ["." number] 804 ; position number of messages in the view 805 ; may be hierarchical if sub-command defines 806 ; hierarchic ordering of messages 807 ; 0 means outside of the current view 809 search-key =/ "VIEW" / "UNVIEW" 810 ; extends [IMAP4] search criteria 811 ; new search criteria are only available 812 ; when a view is in effect 814 select = "SELECT" SP mailbox [SP view-set-arg] 815 ; redefines [IMAP4] SELECT command 817 view = "VIEW" SP (view-set / view-reference) 819 view-mailbox-data = "VIEW" SP (("SEARCH" *(SP position)) / OTHER) 820 ; OTHER reserved for future expansion 822 view-msg-data = nz_number SP "VIEW" SP uniqueid 823 SP position [SP position] 825 view-reference = copy / fetch / store / search 826 ; copy, fetch, store, search defined 827 ; in [IMAP4] 829 view-response = view-msg-data / view-mailbox-data 831 view-set = "SET" [SP view-set-arg] 833 view-set-arg = search / sort / thread / OTHER 834 ; search is defined in [IMAP4] 835 ; sort is defined in [SORT] 836 ; thread is defined in [THREAD] 837 ; OTHER reserved for future definition 839 7 Security Considerations 841 There are no known security issues with this extension. 843 8 References 845 [ABNF] Crocker, Overell, "Augmented BNF for Syntax Specifications: 846 ABNF", RFC 2234, Internet Mail Consortium, Demon Internet Ltd, 847 November 1997. 849 [KEYWORDS] Bradner, "Key words for use in RFCs to Indicate 850 Requirement Levels", RFC 2119, Harvard University, March 1997. 852 [IMAP4] Crispin, M., "Internet Message Access Protocol - Version 853 4rev1", RFC 2060, University of Washington, December 1996. 855 [MIME-IMB] Freed, N., and Borenstein, N.., "MIME (Multipurpose 856 Internet Mail Extensions) Part One: Format of Internet Message 857 Bodies", RFC 2045, November 1996. 859 [RFC-822] Crocker, D., "Standard for the Format of ARPA Internet 860 Text Messages", STD 11, RFC822, August 1982. 862 [SORT] Crispin, M., "Internet Message Access Protocol - SORT 863 Extension", draft-ietf-imapext-sort-03.txt (Work in progress) 865 [THREAD] Crispin, M., "Internet Message Access Protocol - THREAD 866 Extension", draft-crispin-imapext-thread-01.txt (Work in progress) 868 9 Acknowledgments 870 Steve Hole, Chris Newman and Larry Osterman have made significant 871 contributions to the creation and refinement of the ideas expressed 872 in this document. 874 10 Authors' Addresses 876 Cyrus Daboo 877 Cyrusoft International, Inc. 878 Suite 780, 5001 Baum Blvd. 879 Pittsburgh, PA 15213 881 Phone: (412) 605-0499 882 Email: daboo@cyrusoft.com 884 Mark Pustilnik 885 Microsoft 886 1 Microsoft Way 887 Redmond, WA 98052 889 Phone: (425) 703-5758 890 Email: markpu@microsoft.com 892 Mark R. Crispin 893 Networks and Distributed Computing 894 University of Washington 895 4545 15th Avenue NE 896 Seattle, WA 98105-4527 898 Phone: (206) 543-5762 899 EMail: MRC@CAC.Washington.EDU