| < draft-leiba-imap-implement-guide-09.txt | draft-leiba-imap-implement-guide-10.txt > | |||
|---|---|---|---|---|
| Network Working Group B. Leiba | Network Working Group B. Leiba | |||
| Internet Draft IBM T.J. Watson Research Center | Internet Draft IBM T.J. Watson Research Center | |||
| Document: draft-leiba-imap-implement-guide-09.txt May 1999 | Document: draft-leiba-imap-implement-guide-10.txt July 1999 | |||
| Expires October 1999 | Expires January 2000 | |||
| IMAP4 Implementation Recommendations | IMAP4 Implementation Recommendations | |||
| Status of this Document | Status of this Document | |||
| 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. Internet-Drafts are working | all provisions of Section 10 of RFC2026. Internet-Drafts are working | |||
| documents of the Internet Engineering Task Force (IETF), its areas, | documents of the Internet Engineering Task Force (IETF), its areas, | |||
| and its working groups. Note that other groups may also distribute | and its working groups. Note that other groups may also distribute | |||
| working documents as Internet-Drafts. | working documents as Internet-Drafts. | |||
| skipping to change at page 2, line 10 ¶ | skipping to change at page 2, line 10 ¶ | |||
| must be made and issues that must be considered when designing such | must be made and issues that must be considered when designing such | |||
| clients and servers. This document attempts to outline these issues | clients and servers. This document attempts to outline these issues | |||
| and to make recommendations in order to make the end products as | and to make recommendations in order to make the end products as | |||
| interoperable as possible. | interoperable as possible. | |||
| 2. Conventions used in this document | 2. Conventions used in this document | |||
| In examples, "C:" indicates lines sent by a client that is connected | In examples, "C:" indicates lines sent by a client that is connected | |||
| to a server. "S:" indicates lines sent by the server to the client. | to a server. "S:" indicates lines sent by the server to the client. | |||
| The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", | The words "must", "must not", "should", "should not", and "may" are | |||
| "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this | used with specific meaning in this document; since their meaning is | |||
| document are to be interpreted as described in [RFC-2119]. | somewhat different from that specified in RFC 2119, we do not put | |||
| them in all caps here. Their meaning is as follows: | ||||
| must -- This word means that the action described is necessary to ensure | ||||
| interoperability. The recommendation should not be ignored. | ||||
| must not -- This phrase means that the action described will be almost | ||||
| certain to hurt interoperability. The recommendation should not | ||||
| be ignored. | ||||
| should -- This word means that the action described is strongly | ||||
| recommended and will enhance interoperability or usability. The | ||||
| recommendation should not be ignored without careful | ||||
| consideration. | ||||
| should not -- This phrase means that the action described is strongly | ||||
| recommended against, and might hurt interoperability or | ||||
| usability. The recommendation should not be ignored without | ||||
| careful consideration. | ||||
| may -- This word means that the action described is an acceptable | ||||
| implementation choice. No specific recommendation is implied; | ||||
| this word is used to point out a choice that might not be | ||||
| obvious, or to let implementors know what choices have been made | ||||
| by existing implementations. | ||||
| 3. Interoperability Issues and Recommendations | 3. Interoperability Issues and Recommendations | |||
| 3.1. Accessibility | 3.1. Accessibility | |||
| This section describes the issues related to access to servers and | This section describes the issues related to access to servers and | |||
| server resources. Concerns here include data sharing and maintenance | server resources. Concerns here include data sharing and maintenance | |||
| of client/server connections. | of client/server connections. | |||
| 3.1.1. Multiple Accesses of the Same Mailbox | 3.1.1. Multiple Accesses of the Same Mailbox | |||
| skipping to change at page 2, line 34 ¶ | skipping to change at page 3, line 8 ¶ | |||
| One strong point of IMAP4 is that, unlike POP3, it allows for | One strong point of IMAP4 is that, unlike POP3, it allows for | |||
| multiple simultaneous access to a single mailbox. A user can, thus, | multiple simultaneous access to a single mailbox. A user can, thus, | |||
| read mail from a client at home while the client in the office is | read mail from a client at home while the client in the office is | |||
| still connected; or the help desk staff can all work out of the same | still connected; or the help desk staff can all work out of the same | |||
| inbox, all seeing the same pool of questions. An important point | inbox, all seeing the same pool of questions. An important point | |||
| about this capability, though is that NO SERVER IS GUARANTEED TO | about this capability, though is that NO SERVER IS GUARANTEED TO | |||
| SUPPORT THIS. If you are selecting an IMAP server and this facility | SUPPORT THIS. If you are selecting an IMAP server and this facility | |||
| is important to you, be sure that the server you choose to install, | is important to you, be sure that the server you choose to install, | |||
| in the configuration you choose to use, supports it. | in the configuration you choose to use, supports it. | |||
| If you are designing a client, you MUST NOT assume that you can | If you are designing a client, you must not assume that you can | |||
| access the same mailbox more than once at a time. That means | access the same mailbox more than once at a time. That means | |||
| 1. you MUST handle gracefully the failure of a SELECT command if | 1. you must handle gracefully the failure of a SELECT command if | |||
| the server refuses the second SELECT, | the server refuses the second SELECT, | |||
| 2. you MUST handle reasonably the severing of your connection (see | 2. you must handle reasonably the severing of your connection (see | |||
| "Severed Connections", below) if the server chooses to allow the | "Severed Connections", below) if the server chooses to allow the | |||
| second SELECT by forcing the first off, | second SELECT by forcing the first off, | |||
| 3. you MUST avoid making multiple connections to the same mailbox | 3. you must avoid making multiple connections to the same mailbox | |||
| in your own client (for load balancing or other such reasons), | in your own client (for load balancing or other such reasons), | |||
| and | and | |||
| 4. you MUST avoid using the STATUS command on a mailbox that you | 4. you must avoid using the STATUS command on a mailbox that you | |||
| have selected (with some server implementations the STATUS | have selected (with some server implementations the STATUS | |||
| command has the same problems with multiple access as do the | command has the same problems with multiple access as do the | |||
| SELECT and EXAMINE commands). | SELECT and EXAMINE commands). | |||
| A further note about STATUS: The STATUS command is sometimes used to | A further note about STATUS: The STATUS command is sometimes used to | |||
| check a non-selected mailbox for new mail. This mechanism MUST NOT | check a non-selected mailbox for new mail. This mechanism must not | |||
| be used to check for new mail in the selected mailbox; section 5.2 of | be used to check for new mail in the selected mailbox; section 5.2 of | |||
| [RFC-2060] specifically forbids this in its last paragraph. Further, | [RFC-2060] specifically forbids this in its last paragraph. Further, | |||
| since STATUS takes a mailbox name it is an independent operation, not | since STATUS takes a mailbox name it is an independent operation, not | |||
| operating on the selected mailbox. Because of this, the information | operating on the selected mailbox. Because of this, the information | |||
| it returns is not necessarily in synchronization with the selected | it returns is not necessarily in synchronization with the selected | |||
| mailbox state. | mailbox state. | |||
| 3.1.2. Severed Connections | 3.1.2. Severed Connections | |||
| The client/server connection may be severed for one of three reasons: | The client/server connection may be severed for one of three reasons: | |||
| the client severs the connection, the server severs the connection, | the client severs the connection, the server severs the connection, | |||
| or the connection is severed by outside forces beyond the control of | or the connection is severed by outside forces beyond the control of | |||
| the client and the server (a telephone line drops, for example). | the client and the server (a telephone line drops, for example). | |||
| Clients and servers must both deal with these situations. | Clients and servers must both deal with these situations. | |||
| When the client wants to sever a connection, it's usually because it | When the client wants to sever a connection, it's usually because it | |||
| has finished the work it needed to do on that connection. The client | has finished the work it needed to do on that connection. The client | |||
| SHOULD send a LOGOUT command, wait for the tagged response, and then | should send a LOGOUT command, wait for the tagged response, and then | |||
| close the socket. But note that, while this is what's intended in | close the socket. But note that, while this is what's intended in | |||
| the protocol design, there isn't universal agreement here. Some | the protocol design, there isn't universal agreement here. Some | |||
| contend that sending the LOGOUT and waiting for the two responses | contend that sending the LOGOUT and waiting for the two responses | |||
| (untagged BYE and tagged OK) is wasteful and unnecessary, and that | (untagged BYE and tagged OK) is wasteful and unnecessary, and that | |||
| the client can simply close the socket. The server should interpret | the client can simply close the socket. The server should interpret | |||
| the closed socket as a log out by the client. The counterargument is | the closed socket as a log out by the client. The counterargument is | |||
| that it's useful from the standpoint of cleanup, problem | that it's useful from the standpoint of cleanup, problem | |||
| determination, and the like, to have an explicit client log out, | determination, and the like, to have an explicit client log out, | |||
| because otherwise there is no way for the server to tell the | because otherwise there is no way for the server to tell the | |||
| difference between "closed socket because of log out" and "closed | difference between "closed socket because of log out" and "closed | |||
| socket because communication was disrupted". If there is a | socket because communication was disrupted". If there is a | |||
| client/server interaction problem, a client which routinely | client/server interaction problem, a client which routinely | |||
| terminates a session by breaking the connection without a LOGOUT will | terminates a session by breaking the connection without a LOGOUT will | |||
| make it much more difficult to determine the problem. | make it much more difficult to determine the problem. | |||
| Because of this disagreement, server designers must be aware that | Because of this disagreement, server designers must be aware that | |||
| some clients might close the socket without sending a LOGOUT. In any | some clients might close the socket without sending a LOGOUT. In any | |||
| case, whether or not a LOGOUT was sent, the server SHOULD NOT | case, whether or not a LOGOUT was sent, the server should not | |||
| implicitly expunge any messages from the selected mailbox. If a | implicitly expunge any messages from the selected mailbox. If a | |||
| client wants the server to do so, it MUST send a CLOSE or EXPUNGE | client wants the server to do so, it must send a CLOSE or EXPUNGE | |||
| command explicitly. | command explicitly. | |||
| When the server wants to sever a connection it's usually due to an | When the server wants to sever a connection it's usually due to an | |||
| inactivity timeout or is because a situation has arisen that has | inactivity timeout or is because a situation has arisen that has | |||
| changed the state of the mail store in a way that the server can not | changed the state of the mail store in a way that the server can not | |||
| communicate to the client. The server SHOULD send an untagged BYE | communicate to the client. The server should send an untagged BYE | |||
| response to the client and then close the socket. Sending an | response to the client and then close the socket. Sending an | |||
| untagged BYE response before severing allows the server to send a | untagged BYE response before severing allows the server to send a | |||
| human-readable explanation of the problem to the client, which the | human-readable explanation of the problem to the client, which the | |||
| client may then log, display to the user, or both (see section 7.1.5 | client may then log, display to the user, or both (see section 7.1.5 | |||
| of [RFC-2060]). | of [RFC-2060]). | |||
| Regarding inactivity timeouts, there is some controversy. Unlike | Regarding inactivity timeouts, there is some controversy. Unlike | |||
| POP, for which the design is for a client to connect, retrieve mail, | POP, for which the design is for a client to connect, retrieve mail, | |||
| and log out, IMAP<RIGHT SINGLE QUOTATION MARK>s design encourages long-lived (and mostly | and log out, IMAP's design encourages long-lived (and mostly | |||
| inactive) client/server sessions. As the number of users grows, this | inactive) client/server sessions. As the number of users grows, this | |||
| can use up a lot of server resources, especially with clients that | can use up a lot of server resources, especially with clients that | |||
| are designed to maintain sessions for mailboxes that the user has | are designed to maintain sessions for mailboxes that the user has | |||
| finished accessing. To alleviate this, a server MAY implement an | finished accessing. To alleviate this, a server may implement an | |||
| inactivity timeout, unilaterally closing a session (after first | inactivity timeout, unilaterally closing a session (after first | |||
| sending an untagged BYE, as noted above). Some server operators have | sending an untagged BYE, as noted above). Some server operators have | |||
| reported dramatic improvements in server performance after doing | reported dramatic improvements in server performance after doing | |||
| this. As specified in [RFC-2060], if such a timeout is done it MUST | this. As specified in [RFC-2060], if such a timeout is done it must | |||
| NOT be until at least 30 minutes of inactivity. The reason for this | not be until at least 30 minutes of inactivity. The reason for this | |||
| specification is to prevent clients from sending commands (such as | specification is to prevent clients from sending commands (such as | |||
| NOOP) to the server at frequent intervals simply to avert a too-early | NOOP) to the server at frequent intervals simply to avert a too-early | |||
| timeout. If the client knows that the server may not time out the | timeout. If the client knows that the server may not time out the | |||
| session for at least 30 minutes, then the client need not poll at | session for at least 30 minutes, then the client need not poll at | |||
| intervals more frequent than, say, 25 minutes. | intervals more frequent than, say, 25 minutes. | |||
| 3.2. Scaling | 3.2. Scaling | |||
| IMAP4 has many features that allow for scalability, as mail stores | IMAP4 has many features that allow for scalability, as mail stores | |||
| become larger and more numerous. Large numbers of users, mailboxes, | become larger and more numerous. Large numbers of users, mailboxes, | |||
| skipping to change at page 5, line 18 ¶ | skipping to change at page 5, line 34 ¶ | |||
| and other such hierarchical mailbox structures, can be very numerous | and other such hierarchical mailbox structures, can be very numerous | |||
| but may have only a few entries at the top level of hierarchy. Also, | but may have only a few entries at the top level of hierarchy. Also, | |||
| some servers are built against mail stores that can, unbeknownst to | some servers are built against mail stores that can, unbeknownst to | |||
| the server, have circular hierarchies - that is, it's possible for | the server, have circular hierarchies - that is, it's possible for | |||
| "a/b/c/d" to resolve to the same file structure as "a", which would | "a/b/c/d" to resolve to the same file structure as "a", which would | |||
| then mean that "a/b/c/d/b" is the same as "a/b", and the hierarchy | then mean that "a/b/c/d/b" is the same as "a/b", and the hierarchy | |||
| will never end. The LIST response in this case will be unlimited. | will never end. The LIST response in this case will be unlimited. | |||
| Clients that will have trouble with this are those that use | Clients that will have trouble with this are those that use | |||
| C: 001 LIST "" * | C: 001 LIST "" * | |||
| to determine the mailbox list. Because of this, clients SHOULD NOT | to determine the mailbox list. Because of this, clients should not | |||
| use an unqualified "*" that way in the LIST command. A safer | use an unqualified "*" that way in the LIST command. A safer | |||
| approach is to list each level of hierarchy individually, allowing | approach is to list each level of hierarchy individually, allowing | |||
| the user to traverse the tree one limb at a time, thus: | the user to traverse the tree one limb at a time, thus: | |||
| C: 001 LIST "" % | C: 001 LIST "" % | |||
| S: * LIST () "/" Banana | S: * LIST () "/" Banana | |||
| S: * LIST ...etc... | S: * LIST ...etc... | |||
| S: 001 OK done | S: 001 OK done | |||
| and then | and then | |||
| C: 002 LIST "" Banana/% | C: 002 LIST "" Banana/% | |||
| skipping to change at page 5, line 35 ¶ | skipping to change at page 6, line 4 ¶ | |||
| S: * LIST ...etc... | S: * LIST ...etc... | |||
| S: 001 OK done | S: 001 OK done | |||
| and then | and then | |||
| C: 002 LIST "" Banana/% | C: 002 LIST "" Banana/% | |||
| S: * LIST () "/" Banana/Apple | S: * LIST () "/" Banana/Apple | |||
| S: * LIST ...etc... | S: * LIST ...etc... | |||
| S: 002 OK done | S: 002 OK done | |||
| Using this technique the client's user interface can give the user | Using this technique the client's user interface can give the user | |||
| full flexibility without choking on the voluminous reply to "LIST *". | full flexibility without choking on the voluminous reply to "LIST *". | |||
| Of course, it is still possible that the reply to | Of course, it is still possible that the reply to | |||
| C: 005 LIST "" alt.fan.celebrity.% | C: 005 LIST "" alt.fan.celebrity.% | |||
| may be thousands of entries long, and there is, unfortunately, | may be thousands of entries long, and there is, unfortunately, | |||
| nothing the client can do to protect itself from that. This has not | nothing the client can do to protect itself from that. This has not | |||
| yet been a notable problem. | yet been a notable problem. | |||
| Servers that may export circular hierarchies (any server that | Servers that may export circular hierarchies (any server that | |||
| directly presents a UNIX file system, for instance) SHOULD limit the | directly presents a UNIX file system, for instance) should limit the | |||
| hierarchy depth to prevent unlimited LIST responses. A suggested | hierarchy depth to prevent unlimited LIST responses. A suggested | |||
| depth limit is 20 hierarchy levels. | depth limit is 20 hierarchy levels. | |||
| 3.2.1.2. Fetching the List of Messages | 3.2.1.2. Fetching the List of Messages | |||
| When a client selects a mailbox, it is given a count, in the untagged | When a client selects a mailbox, it is given a count, in the untagged | |||
| EXISTS response, of the messages in the mailbox. This number can be | EXISTS response, of the messages in the mailbox. This number can be | |||
| very large. In such a case it might be unwise to use | very large. In such a case it might be unwise to use | |||
| C: 004 FETCH 1:* ALL | C: 004 FETCH 1:* ALL | |||
| to populate the user's view of the mailbox. One good method to avoid | to populate the user's view of the mailbox. One good method to avoid | |||
| skipping to change at page 6, line 47 ¶ | skipping to change at page 7, line 23 ¶ | |||
| ... etc... | ... etc... | |||
| If the server does not return an OK [UNSEEN] response, the client may | If the server does not return an OK [UNSEEN] response, the client may | |||
| use SEARCH UNSEEN to obtain that value. | use SEARCH UNSEEN to obtain that value. | |||
| This mechanism is good as a default presentation method, but only | This mechanism is good as a default presentation method, but only | |||
| works well if the default message order is acceptable. A client may | works well if the default message order is acceptable. A client may | |||
| want to present various sort orders to the user (by subject, by date | want to present various sort orders to the user (by subject, by date | |||
| sent, by sender, and so on) and in that case (lacking a SORT | sent, by sender, and so on) and in that case (lacking a SORT | |||
| extension on the server side) the client WILL have to retrieve all | extension on the server side) the client WILL have to retrieve all | |||
| message descriptors. A client that provides this service SHOULD NOT | message descriptors. A client that provides this service should not | |||
| do it by default and SHOULD inform the user of the costs of choosing | do it by default and should inform the user of the costs of choosing | |||
| this option for large mailboxes. | this option for large mailboxes. | |||
| 3.2.1.3. Fetching a Large Body Part | 3.2.1.3. Fetching a Large Body Part | |||
| The issue here is similar to the one for a list of messages. In the | The issue here is similar to the one for a list of messages. In the | |||
| BODYSTRUCTURE response the client knows the size, in bytes, of the | BODYSTRUCTURE response the client knows the size, in bytes, of the | |||
| body part it plans to fetch. Suppose this is a 70 MB video clip. | body part it plans to fetch. Suppose this is a 70 MB video clip. | |||
| The client can use partial fetches to retrieve the body part in | The client can use partial fetches to retrieve the body part in | |||
| pieces, avoiding the problem of an uninterruptible 70 MB literal | pieces, avoiding the problem of an uninterruptible 70 MB literal | |||
| coming back from the server: | coming back from the server: | |||
| skipping to change at page 7, line 49 ¶ | skipping to change at page 8, line 23 ¶ | |||
| Some clients, rather than using FETCH BODYSTRUCTURE, use FETCH BODY[] | Some clients, rather than using FETCH BODYSTRUCTURE, use FETCH BODY[] | |||
| (or the equivalent FETCH RFC822) to retrieve the entire message. | (or the equivalent FETCH RFC822) to retrieve the entire message. | |||
| They then do the MIME parsing in the client. This may give the | They then do the MIME parsing in the client. This may give the | |||
| client slightly more flexibility in some areas (access, for instance, | client slightly more flexibility in some areas (access, for instance, | |||
| to header fields that aren't returned in the BODYSTRUCTURE and | to header fields that aren't returned in the BODYSTRUCTURE and | |||
| ENVELOPE responses), but it can cause severe performance problems by | ENVELOPE responses), but it can cause severe performance problems by | |||
| forcing the transfer of all body parts when the user might only want | forcing the transfer of all body parts when the user might only want | |||
| to see some of them - a user logged on by modem and reading a small | to see some of them - a user logged on by modem and reading a small | |||
| text message with a large ZIP file attached may prefer to read the | text message with a large ZIP file attached may prefer to read the | |||
| text only and save the ZIP file for later. Therefore, a client | text only and save the ZIP file for later. Therefore, a client | |||
| SHOULD NOT normally retrieve entire messages and SHOULD retrieve | should not normally retrieve entire messages and should retrieve | |||
| message body parts selectively. | message body parts selectively. | |||
| 3.2.1.5. Long Command Lines | 3.2.1.5. Long Command Lines | |||
| A client can wind up building a very long command line in an effort | A client can wind up building a very long command line in an effort | |||
| to try to be efficient about requesting information from a server. | to try to be efficient about requesting information from a server. | |||
| This can typically happen when a client builds a message set from | This can typically happen when a client builds a message set from | |||
| selected messages and doesn't recognise that contiguous blocks of | selected messages and doesn't recognise that contiguous blocks of | |||
| messages may be group in a range. Suppose a user selects all 10,000 | messages may be group in a range. Suppose a user selects all 10,000 | |||
| messages in a large mailbox and then unselects message 287. The | messages in a large mailbox and then unselects message 287. The | |||
| client could build that message set as "1:286,288:10000", but a | client could build that message set as "1:286,288:10000", but a | |||
| client that doesn't handle that might try to enumerate each message | client that doesn't handle that might try to enumerate each message | |||
| individually and build "1,2,3,4, [and so on] ,9999,10000". Adding | individually and build "1,2,3,4, [and so on] ,9999,10000". Adding | |||
| that to the fetch command results in a command line that's almost | that to the fetch command results in a command line that's almost | |||
| 49,000 octets long, and, clearly, one can construct a command line | 49,000 octets long, and, clearly, one can construct a command line | |||
| that's even longer. | that's even longer. | |||
| A client SHOULD limit the length of the command lines it generates to | A client should limit the length of the command lines it generates to | |||
| approximately 1000 octets (including all quoted strings but not | approximately 1000 octets (including all quoted strings but not | |||
| including literals). If the client is unable to group things into | including literals). If the client is unable to group things into | |||
| ranges so that the command line is within that length, it SHOULD | ranges so that the command line is within that length, it should | |||
| split the request into multiple commands. The client SHOULD use | split the request into multiple commands. The client should use | |||
| literals instead of long quoted strings, in order to keep the command | literals instead of long quoted strings, in order to keep the command | |||
| length down. | length down. | |||
| For its part, a server SHOULD allow for a command line of at least | For its part, a server should allow for a command line of at least | |||
| 8000 octets. This provides plenty of leeway for accepting reasonable | 8000 octets. This provides plenty of leeway for accepting reasonable | |||
| length commands from clients. The server SHOULD send a BAD response | length commands from clients. The server should send a BAD response | |||
| to a command that does not end within the server's maximum accepted | to a command that does not end within the server's maximum accepted | |||
| command length. | command length. | |||
| 3.2.2. Subscriptions | 3.2.2. Subscriptions | |||
| The client isn't the only entity that can get flooded: the end user, | The client isn't the only entity that can get flooded: the end user, | |||
| too, may need some flood control. The IMAP4 protocol provides such | too, may need some flood control. The IMAP4 protocol provides such | |||
| control in the form of subscriptions. Most servers support the | control in the form of subscriptions. Most servers support the | |||
| SUBSCRIBE, UNSUBSCRIBE, and LSUB commands, and many users choose to | SUBSCRIBE, UNSUBSCRIBE, and LSUB commands, and many users choose to | |||
| narrow down a large list of available mailboxes by subscribing to the | narrow down a large list of available mailboxes by subscribing to the | |||
| ones that they usually want to see. Clients, with this in mind, | ones that they usually want to see. Clients, with this in mind, | |||
| SHOULD give the user a way to see only subscribed mailboxes. A | should give the user a way to see only subscribed mailboxes. A | |||
| client that never uses the LSUB command takes a significant usability | client that never uses the LSUB command takes a significant usability | |||
| feature away from the user. Of course, the client would not want to | feature away from the user. Of course, the client would not want to | |||
| hide the LIST command completely; the user needs to have a way to | hide the LIST command completely; the user needs to have a way to | |||
| choose between LIST and LSUB. The usual way to do this is to provide | choose between LIST and LSUB. The usual way to do this is to provide | |||
| a setting like "show which mailboxes?: [] all [] subscribed only". | a setting like "show which mailboxes?: [] all [] subscribed only". | |||
| 3.2.3. Searching | 3.2.3. Searching | |||
| IMAP SEARCH commands can become particularly troublesome (that is, | IMAP SEARCH commands can become particularly troublesome (that is, | |||
| slow) on mailboxes containing a large number of messages. So let's | slow) on mailboxes containing a large number of messages. So let's | |||
| put a few things in perspective in that regard. | put a few things in perspective in that regard. | |||
| The flag searches SHOULD be fast. The flag searches (ALL, [UN]SEEN, | The flag searches should be fast. The flag searches (ALL, [UN]SEEN, | |||
| [UN]ANSWERED, [UN]DELETED, [UN]DRAFT, [UN]FLAGGED, NEW, OLD, RECENT) | [UN]ANSWERED, [UN]DELETED, [UN]DRAFT, [UN]FLAGGED, NEW, OLD, RECENT) | |||
| are known to be used by clients for the client's own use (for | are known to be used by clients for the client's own use (for | |||
| instance, some clients use "SEARCH UNSEEN" to find unseen mail and | instance, some clients use "SEARCH UNSEEN" to find unseen mail and | |||
| "SEARCH DELETED" to warn the user before expunging messages). | "SEARCH DELETED" to warn the user before expunging messages). | |||
| Other searches, particularly the text searches (HEADER, TEXT, BODY) | Other searches, particularly the text searches (HEADER, TEXT, BODY) | |||
| are initiated by the user, rather than by the client itself, and | are initiated by the user, rather than by the client itself, and | |||
| somewhat slower performance can be tolerated, since the user is aware | somewhat slower performance can be tolerated, since the user is aware | |||
| that the search is being done (and is probably aware that it might be | that the search is being done (and is probably aware that it might be | |||
| time-consuming). A smart server might use dynamic indexing to speed | time-consuming). A smart server might use dynamic indexing to speed | |||
| commonly used text searches. | commonly used text searches. | |||
| The client MAY allow other commands to be sent to the server while a | The client may allow other commands to be sent to the server while a | |||
| SEARCH is in progress, but at the time of this writing there is | SEARCH is in progress, but at the time of this writing there is | |||
| little or no server support for parallel processing of multiple | little or no server support for parallel processing of multiple | |||
| commands in the same session (and see "Multiple Accesses of the Same | commands in the same session (and see "Multiple Accesses of the Same | |||
| Mailbox" above for a description of the dangers of trying to work | Mailbox" above for a description of the dangers of trying to work | |||
| around this by doing your SEARCH in another session). | around this by doing your SEARCH in another session). | |||
| Another word about text searches: some servers, built on database | Another word about text searches: some servers, built on database | |||
| back-ends with indexed search capabilities, may return search results | back-ends with indexed search capabilities, may return search results | |||
| that do not match the IMAP spec's "case-insensitive substring" | that do not match the IMAP spec's "case-insensitive substring" | |||
| requirements. While these servers are in violation of the protocol, | requirements. While these servers are in violation of the protocol, | |||
| there is little harm in the violation as long as the search results | there is little harm in the violation as long as the search results | |||
| are used only in response to a user's request. Still, developers of | are used only in response to a user's request. Still, developers of | |||
| such servers should be aware that they ARE violating the protocol, | such servers should be aware that they ARE violating the protocol, | |||
| should think carefully about that behaviour, and MUST be certain that | should think carefully about that behaviour, and must be certain that | |||
| their servers respond accurately to the flag searches for the reasons | their servers respond accurately to the flag searches for the reasons | |||
| outlined above. | outlined above. | |||
| In addition, servers SHOULD support CHARSET UTF-8 [UTF-8] in | In addition, servers should support CHARSET UTF-8 [UTF-8] in | |||
| searches. | searches. | |||
| 3.3 Avoiding Invalid Requests | 3.3 Avoiding Invalid Requests | |||
| IMAP4 provides ways for a server to tell a client in advance what is | IMAP4 provides ways for a server to tell a client in advance what is | |||
| and isn't permitted in some circumstances. Clients SHOULD use these | and isn't permitted in some circumstances. Clients should use these | |||
| features to avoid sending requests that a well designed client would | features to avoid sending requests that a well designed client would | |||
| know to be invalid. This section explains this in more detail. | know to be invalid. This section explains this in more detail. | |||
| 3.3.1. The CAPABILITY Command | 3.3.1. The CAPABILITY Command | |||
| All IMAP4 clients SHOULD use the CAPABILITY command to determine what | All IMAP4 clients should use the CAPABILITY command to determine what | |||
| version of IMAP and what optional features a server supports. The | version of IMAP and what optional features a server supports. The | |||
| client SHOULD NOT send IMAP4rev1 commands and arguments to a server | client should not send IMAP4rev1 commands and arguments to a server | |||
| that does not advertize IMAP4rev1 in its CAPABILITY response. | that does not advertize IMAP4rev1 in its CAPABILITY response. | |||
| Similarly, the client SHOULD NOT send IMAP4 commands that no longer | Similarly, the client should not send IMAP4 commands that no longer | |||
| exist in IMAP4rev1 to a server that does not advertize IMAP4 in its | exist in IMAP4rev1 to a server that does not advertize IMAP4 in its | |||
| CAPABILITY response. An IMAP4rev1 server is NOT required to support | CAPABILITY response. An IMAP4rev1 server is NOT required to support | |||
| obsolete IMAP4 or IMAP2bis commands (though some do; do not let this | obsolete IMAP4 or IMAP2bis commands (though some do; do not let this | |||
| fact lull you into thinking that it's valid to send such commands to | fact lull you into thinking that it's valid to send such commands to | |||
| an IMAP4rev1 server). | an IMAP4rev1 server). | |||
| A client SHOULD NOT send commands to probe for the existance of | A client should not send commands to probe for the existance of | |||
| certain extensions. All standard and standards-track extensions | certain extensions. All standard and standards-track extensions | |||
| include CAPABILITY tokens indicating their presense. All private and | include CAPABILITY tokens indicating their presense. All private and | |||
| experimental extensions SHOULD do the same, and clients that take | experimental extensions should do the same, and clients that take | |||
| advantage of them SHOULD use the CAPABILITY response to determine | advantage of them should use the CAPABILITY response to determine | |||
| whether they may be used or not. | whether they may be used or not. | |||
| 3.3.2. Don't Do What the Server Says You Can't | 3.3.2. Don't Do What the Server Says You Can't | |||
| In many cases, the server, in response to a command, will tell the | In many cases, the server, in response to a command, will tell the | |||
| client something about what can and can't be done with a particular | client something about what can and can't be done with a particular | |||
| mailbox. The client SHOULD pay attention to this information and | mailbox. The client should pay attention to this information and | |||
| SHOULD NOT try to do things that it's been told it can't do. | should not try to do things that it's been told it can't do. | |||
| Examples: | Examples: | |||
| * Do not try to SELECT a mailbox that has the \Noselect flag set. | * Do not try to SELECT a mailbox that has the \Noselect flag set. | |||
| * Do not try to CREATE a sub-mailbox in a mailbox that has the | * Do not try to CREATE a sub-mailbox in a mailbox that has the | |||
| \Noinferiors flag set. | \Noinferiors flag set. | |||
| * Do not respond to a failing COPY or APPEND command by trying to | * Do not respond to a failing COPY or APPEND command by trying to | |||
| CREATE the target mailbox if the server does not respond with a | CREATE the target mailbox if the server does not respond with a | |||
| [TRYCREATE] response code. | [TRYCREATE] response code. | |||
| * Do not try to expunge a mailbox that has been selected with the | * Do not try to expunge a mailbox that has been selected with the | |||
| [READ-ONLY] response code. | [READ-ONLY] response code. | |||
| 3.4. Miscellaneous Protocol Considerations | 3.4. Miscellaneous Protocol Considerations | |||
| skipping to change at page 11, line 23 ¶ | skipping to change at page 11, line 45 ¶ | |||
| NOT an RFC-822 date string - that is, it is not in the same format as | NOT an RFC-822 date string - that is, it is not in the same format as | |||
| the first string in the ENVELOPE response. Since most clients will, | the first string in the ENVELOPE response. Since most clients will, | |||
| in fact, accept an RFC-822 date string in the INTERNALDATE response, | in fact, accept an RFC-822 date string in the INTERNALDATE response, | |||
| it's easy to miss this in your interoperability testing. But it will | it's easy to miss this in your interoperability testing. But it will | |||
| cause a problem with some client, so be sure to generate the correct | cause a problem with some client, so be sure to generate the correct | |||
| string for this field. | string for this field. | |||
| 3.4.2. Special Characters | 3.4.2. Special Characters | |||
| Certain characters, currently the double-quote and the backslash, may | Certain characters, currently the double-quote and the backslash, may | |||
| not be sent as-is inside a quoted string. These characters MUST be | not be sent as-is inside a quoted string. These characters must be | |||
| preceded by the escape character if they are in a quoted string, or | preceded by the escape character if they are in a quoted string, or | |||
| else the string MUST be sent as a literal. Both clients and servers | else the string must be sent as a literal. Both clients and servers | |||
| MUST handle this, both on output (they MUST send these characters | must handle this, both on output (they must send these characters | |||
| properly) and on input (they MUST be able to receive escaped | properly) and on input (they must be able to receive escaped | |||
| characters in quoted strings). Example: | characters in quoted strings). Example: | |||
| C: 001 LIST "" % | C: 001 LIST "" % | |||
| S: * LIST () "" INBOX | S: * LIST () "" INBOX | |||
| S: * LIST () "\\" TEST | S: * LIST () "\\" TEST | |||
| S: * LIST () "\\" {12} | S: * LIST () "\\" {12} | |||
| S: "My" mailbox | S: "My" mailbox | |||
| S: 001 OK done | S: 001 OK done | |||
| C: 002 LIST "" "\"My\" mailbox\\%" | C: 002 LIST "" "\"My\" mailbox\\%" | |||
| S: * LIST () "\\" {17} | S: * LIST () "\\" {17} | |||
| skipping to change at page 12, line 5 ¶ | skipping to change at page 12, line 29 ¶ | |||
| containing imbedded double-quotes as a literal. The client used only | containing imbedded double-quotes as a literal. The client used only | |||
| quoted strings, escaping both the backslash and the double-quote | quoted strings, escaping both the backslash and the double-quote | |||
| characters. | characters. | |||
| The CR and LF characters may be sent ONLY in literals; they are not | The CR and LF characters may be sent ONLY in literals; they are not | |||
| allowed, even if escaped, inside quoted strings. | allowed, even if escaped, inside quoted strings. | |||
| And while we're talking about special characters: the IMAP spec, in | And while we're talking about special characters: the IMAP spec, in | |||
| the section titled "Mailbox International Naming Convention", | the section titled "Mailbox International Naming Convention", | |||
| describes how to encode mailbox names in modified UTF-7 [UTF-7 and | describes how to encode mailbox names in modified UTF-7 [UTF-7 and | |||
| RFC-2060]. Implementations MUST adhere to this in order to be | RFC-2060]. Implementations must adhere to this in order to be | |||
| interoperable in the international market, and servers SHOULD | interoperable in the international market, and servers should | |||
| validate mailbox names sent by client and reject names that do not | validate mailbox names sent by client and reject names that do not | |||
| conform. | conform. | |||
| As to special characters in userids and passwords: clients MUST NOT | As to special characters in userids and passwords: clients must not | |||
| restrict what a user may type in for a userid or a password. The | restrict what a user may type in for a userid or a password. The | |||
| formal grammar specifies that these are "astrings", and an astring | formal grammar specifies that these are "astrings", and an astring | |||
| can be a literal. A literal, in turn can contain any 8-bit | can be a literal. A literal, in turn can contain any 8-bit | |||
| character, and clients MUST allow users to enter all 8-bit characters | character, and clients must allow users to enter all 8-bit characters | |||
| here, and MUST pass them, unchanged, to the server (being careful to | here, and must pass them, unchanged, to the server (being careful to | |||
| send them as literals when necessary). In particular, some server | send them as literals when necessary). In particular, some server | |||
| configurations use "@" in user names, and some clients do not allow | configurations use "@" in user names, and some clients do not allow | |||
| that character to be entered; this creates a severe interoperability | that character to be entered; this creates a severe interoperability | |||
| problem. | problem. | |||
| 3.4.3. UIDs and UIDVALIDITY | 3.4.3. UIDs and UIDVALIDITY | |||
| Servers that support existing back-end mail stores often have no good | Servers that support existing back-end mail stores often have no good | |||
| place to save UIDs for messages. Often the existing mail store will | place to save UIDs for messages. Often the existing mail store will | |||
| not have the concept of UIDs in the sense that IMAP has: strictly | not have the concept of UIDs in the sense that IMAP has: strictly | |||
| increasing, never re-issued, 32-bit integers. Some servers solve | increasing, never re-issued, 32-bit integers. Some servers solve | |||
| this by storing the UIDs in a place that's accessible to end users, | this by storing the UIDs in a place that's accessible to end users, | |||
| allowing for the possibility that the users will delete them. Others | allowing for the possibility that the users will delete them. Others | |||
| solve it by re-assigning UIDs every time a mailbox is selected. | solve it by re-assigning UIDs every time a mailbox is selected. | |||
| The server SHOULD maintain UIDs permanently for all messages if it | The server should maintain UIDs permanently for all messages if it | |||
| can. If that's not possible, the server MUST change the UIDVALIDITY | can. If that's not possible, the server must change the UIDVALIDITY | |||
| value for the mailbox whenever any of the UIDs may have become | value for the mailbox whenever any of the UIDs may have become | |||
| invalid. Clients MUST recognize that the UIDVALIDITY has changed and | invalid. Clients must recognize that the UIDVALIDITY has changed and | |||
| MUST respond to that condition by throwing away any information that | must respond to that condition by throwing away any information that | |||
| they have saved about UIDs in that mailbox. There have been many | they have saved about UIDs in that mailbox. There have been many | |||
| problems in this area when clients have failed to do this; in the | problems in this area when clients have failed to do this; in the | |||
| worst case it will result in loss of mail when a client deletes the | worst case it will result in loss of mail when a client deletes the | |||
| wrong piece of mail by using a stale UID. | wrong piece of mail by using a stale UID. | |||
| It seems to be a common misunderstanding that "the UIDVALIDITY and | It seems to be a common misunderstanding that "the UIDVALIDITY and | |||
| the UID, taken together, form a 64-bit identifier that uniquely | the UID, taken together, form a 64-bit identifier that uniquely | |||
| identifies a message on a server". This is absolutely NOT TRUE. | identifies a message on a server". This is absolutely NOT TRUE. | |||
| There is no assurance that the UIDVALIDITY values of two mailboxes be | There is no assurance that the UIDVALIDITY values of two mailboxes be | |||
| different, so the UIDVALIDITY in no way identifies a mailbox. The | different, so the UIDVALIDITY in no way identifies a mailbox. The | |||
| skipping to change at page 13, line 30 ¶ | skipping to change at page 14, line 5 ¶ | |||
| What's worse is that if you have to wrap the UIDs, and, thus, you | What's worse is that if you have to wrap the UIDs, and, thus, you | |||
| have to change UIDVALIDITY and invalidate the UIDs in the mailbox, | have to change UIDVALIDITY and invalidate the UIDs in the mailbox, | |||
| you have to do it for EVERY mailbox in the system, since they all | you have to do it for EVERY mailbox in the system, since they all | |||
| share the same UID pool. If you assign UIDs per mailbox and you have | share the same UID pool. If you assign UIDs per mailbox and you have | |||
| a problem, you only have to kill the UIDs for that one mailbox. | a problem, you only have to kill the UIDs for that one mailbox. | |||
| Under extreme circumstances (and this is extreme, indeed), the server | Under extreme circumstances (and this is extreme, indeed), the server | |||
| may have to invalidate UIDs while a mailbox is in use by a client - | may have to invalidate UIDs while a mailbox is in use by a client - | |||
| that is, the UIDs that the client knows about in its active mailbox | that is, the UIDs that the client knows about in its active mailbox | |||
| are no longer valid. In that case, the server MUST immediately | are no longer valid. In that case, the server must immediately | |||
| change the UIDVALIDITY and MUST communicate this to the client. The | change the UIDVALIDITY and must communicate this to the client. The | |||
| server MAY do this by sending an unsolicited UIDVALIDITY message, in | server may do this by sending an unsolicited UIDVALIDITY message, in | |||
| the same form as in response to the SELECT command. Clients MUST be | the same form as in response to the SELECT command. Clients must be | |||
| prepared to handle such a message and the possibly coincident failure | prepared to handle such a message and the possibly coincident failure | |||
| of the command in process. For example: | of the command in process. For example: | |||
| C: 032 UID STORE 382 +Flags.silent \Deleted | C: 032 UID STORE 382 +Flags.silent \Deleted | |||
| S: * OK [UIDVALIDITY 12345] New UIDVALIDITY value! | S: * OK [UIDVALIDITY 12345] New UIDVALIDITY value! | |||
| S: 032 NO UID command rejected because UIDVALIDITY changed! | S: 032 NO UID command rejected because UIDVALIDITY changed! | |||
| C: ...invalidates local information and re-fetches... | C: ...invalidates local information and re-fetches... | |||
| C: 033 FETCH 1:* UID | C: 033 FETCH 1:* UID | |||
| ...etc... | ...etc... | |||
| skipping to change at page 14, line 10 ¶ | skipping to change at page 14, line 34 ¶ | |||
| is delivered to the user, which creates the real INBOX file and | is delivered to the user, which creates the real INBOX file and | |||
| assigns a permanent UIDVALIDITY (that is likely not to be 1). The | assigns a permanent UIDVALIDITY (that is likely not to be 1). The | |||
| server reports the change of UIDVALIDITY, but as there were no | server reports the change of UIDVALIDITY, but as there were no | |||
| messages before, so no UIDs have actually changed, all the client | messages before, so no UIDs have actually changed, all the client | |||
| must do is accept the change in UIDVALIDITY. | must do is accept the change in UIDVALIDITY. | |||
| Alternatively, a server may force the client to re-select the | Alternatively, a server may force the client to re-select the | |||
| mailbox, at which time it will obtain a new UIDVALIDITY value. To do | mailbox, at which time it will obtain a new UIDVALIDITY value. To do | |||
| this, the server closes this client session (see "Severed | this, the server closes this client session (see "Severed | |||
| Connections" above) and the client then reconnects and gets back in | Connections" above) and the client then reconnects and gets back in | |||
| synch. Clients MUST be prepared for either of these behaviours. | synch. Clients must be prepared for either of these behaviours. | |||
| We do not know of, nor do we anticipate the future existance of, a | We do not know of, nor do we anticipate the future existance of, a | |||
| server that changes UIDVALIDITY while there are existing messages, | server that changes UIDVALIDITY while there are existing messages, | |||
| but clients MUST be prepared to handle this eventuality. | but clients must be prepared to handle this eventuality. | |||
| 3.4.4. FETCH Responses | 3.4.4. FETCH Responses | |||
| When a client asks for certain information in a FETCH command, the | When a client asks for certain information in a FETCH command, the | |||
| server MAY return the requested information in any order, not | server may return the requested information in any order, not | |||
| necessarily in the order that it was requested. Further, the server | necessarily in the order that it was requested. Further, the server | |||
| MAY return the information in separate FETCH responses and MAY also | may return the information in separate FETCH responses and may also | |||
| return information that was not explicitly requested (to reflect to | return information that was not explicitly requested (to reflect to | |||
| the client changes in the state of the subject message). Some | the client changes in the state of the subject message). Some | |||
| examples: | examples: | |||
| C: 001 FETCH 1 UID FLAGS INTERNALDATE | C: 001 FETCH 1 UID FLAGS INTERNALDATE | |||
| S: * 5 FETCH (FLAGS (\Deleted)) | S: * 5 FETCH (FLAGS (\Deleted)) | |||
| S: * 1 FETCH (FLAGS (\Seen) INTERNALDATE "..." UID 345) | S: * 1 FETCH (FLAGS (\Seen) INTERNALDATE "..." UID 345) | |||
| S: 001 OK done | S: 001 OK done | |||
| (In this case, the responses are in a different order. Also, the | (In this case, the responses are in a different order. Also, the | |||
| server returned a flag update for message 5, which wasn't part of the | server returned a flag update for message 5, which wasn't part of the | |||
| skipping to change at page 14, line 50 ¶ | skipping to change at page 15, line 29 ¶ | |||
| returned in separate responses.) | returned in separate responses.) | |||
| C: 003 FETCH 2 BODY[1] | C: 003 FETCH 2 BODY[1] | |||
| S: * 2 FETCH (FLAGS (\Seen) BODY[1] {14} | S: * 2 FETCH (FLAGS (\Seen) BODY[1] {14} | |||
| S: Hello world! | S: Hello world! | |||
| S: ) | S: ) | |||
| S: 003 OK done | S: 003 OK done | |||
| (In this case, the FLAGS response was added by the server, since | (In this case, the FLAGS response was added by the server, since | |||
| fetching the body part caused the server to set the \Seen flag.) | fetching the body part caused the server to set the \Seen flag.) | |||
| Because of this characteristic a client MUST be ready to receive any | Because of this characteristic a client must be ready to receive any | |||
| FETCH response at any time and should use that information to update | FETCH response at any time and should use that information to update | |||
| its local information about the message to which the FETCH response | its local information about the message to which the FETCH response | |||
| refers. A client MUST NOT assume that any FETCH responses will come | refers. A client must not assume that any FETCH responses will come | |||
| in any particular order, or even that any will come at all. If after | in any particular order, or even that any will come at all. If after | |||
| receiving the tagged response for a FETCH command the client finds | receiving the tagged response for a FETCH command the client finds | |||
| that it did not get all of the information requested, the client | that it did not get all of the information requested, the client | |||
| SHOULD send a NOOP command to the server to ensure that the server | should send a NOOP command to the server to ensure that the server | |||
| has an opportunity to send any pending EXPUNGE responses to the | has an opportunity to send any pending EXPUNGE responses to the | |||
| client (see [RFC-2180]). | client (see [RFC-2180]). | |||
| 3.4.5. RFC822.SIZE | 3.4.5. RFC822.SIZE | |||
| Some back-end mail stores keep the mail in a canonical form, rather | Some back-end mail stores keep the mail in a canonical form, rather | |||
| than retaining the original MIME format of the messages. This means | than retaining the original MIME format of the messages. This means | |||
| that the server must reassemble the message to produce a MIME stream | that the server must reassemble the message to produce a MIME stream | |||
| when a client does a fetch such as RFC822 or BODY[], requesting the | when a client does a fetch such as RFC822 or BODY[], requesting the | |||
| entire message. It also may mean that the server has no convenient | entire message. It also may mean that the server has no convenient | |||
| way to know the RFC822.SIZE of the message. Often, such a server | way to know the RFC822.SIZE of the message. Often, such a server | |||
| will actually have to build the MIME stream to compute the size, only | will actually have to build the MIME stream to compute the size, only | |||
| to throw the stream away and report the size to the client. | to throw the stream away and report the size to the client. | |||
| When this is the case, some servers have chosen to estimate the size, | When this is the case, some servers have chosen to estimate the size, | |||
| rather than to compute it precisely. Such an estimate allows the | rather than to compute it precisely. Such an estimate allows the | |||
| client to display an approximate size to the user and to use the | client to display an approximate size to the user and to use the | |||
| estimate in flood control considerations (q.v.), but requires that | estimate in flood control considerations (q.v.), but requires that | |||
| the client not use the size for things such as allocation of buffers, | the client not use the size for things such as allocation of buffers, | |||
| because those buffers might then be too small to hold the actual MIME | because those buffers might then be too small to hold the actual MIME | |||
| stream. Instead, a client SHOULD use the size that's returned in the | stream. Instead, a client should use the size that's returned in the | |||
| literal when you fetch the data. | literal when you fetch the data. | |||
| The protocol requires that the RFC822.SIZE value returned by the | The protocol requires that the RFC822.SIZE value returned by the | |||
| server be EXACT. Estimating the size is a protocol violation, and | server be EXACT. Estimating the size is a protocol violation, and | |||
| server designers must be aware that, despite the performance savings | server designers must be aware that, despite the performance savings | |||
| they might realize in using an estimate, this practice will cause | they might realize in using an estimate, this practice will cause | |||
| some clients to fail in various ways. If possible, the server SHOULD | some clients to fail in various ways. If possible, the server should | |||
| compute the RFC822.SIZE for a particular message once, and then save | compute the RFC822.SIZE for a particular message once, and then save | |||
| it for later retrieval. If that's not possible, the server MUST | it for later retrieval. If that's not possible, the server must | |||
| compute the value exactly every time. Incorrect estimates do cause | compute the value exactly every time. Incorrect estimates do cause | |||
| severe interoperability problems with some clients. | severe interoperability problems with some clients. | |||
| 3.4.6. Expunged Messages | 3.4.6. Expunged Messages | |||
| If the server allows multiple connections to the same mailbox, it is | If the server allows multiple connections to the same mailbox, it is | |||
| often possible for messages to be expunged in one client unbeknownst | often possible for messages to be expunged in one client unbeknownst | |||
| to another client. Since the server is not allowed to tell the | to another client. Since the server is not allowed to tell the | |||
| client about these expunged messages in response to a FETCH command, | client about these expunged messages in response to a FETCH command, | |||
| the server may have to deal with the issue of how to return | the server may have to deal with the issue of how to return | |||
| skipping to change at page 16, line 16 ¶ | skipping to change at page 16, line 41 ¶ | |||
| explanation and for recommendations. | explanation and for recommendations. | |||
| 3.4.7. The Namespace Issue | 3.4.7. The Namespace Issue | |||
| Namespaces are a very muddy area in IMAP4 implementation right now | Namespaces are a very muddy area in IMAP4 implementation right now | |||
| (see [NAMESPACE] for a proposal to clear the water a bit). Until the | (see [NAMESPACE] for a proposal to clear the water a bit). Until the | |||
| issue is resolved, the important thing for client developers to | issue is resolved, the important thing for client developers to | |||
| understand is that some servers provide access through IMAP to more | understand is that some servers provide access through IMAP to more | |||
| than just the user's personal mailboxes, and, in fact, the user's | than just the user's personal mailboxes, and, in fact, the user's | |||
| personal mailboxes may be "hidden" somewhere in the user's default | personal mailboxes may be "hidden" somewhere in the user's default | |||
| hierarchy. The client, therefore, SHOULD provide a setting wherein | hierarchy. The client, therefore, should provide a setting wherein | |||
| the user can specify a prefix to be used when accessing mailboxes. | the user can specify a prefix to be used when accessing mailboxes. | |||
| If the user's mailboxes are all in "~/mail/", for instance, then the | If the user's mailboxes are all in "~/mail/", for instance, then the | |||
| user can put that string in the prefix. The client would then put | user can put that string in the prefix. The client would then put | |||
| the prefix in front of any name pattern in the LIST and LSUB | the prefix in front of any name pattern in the LIST and LSUB | |||
| commands: | commands: | |||
| C: 001 LIST "" ~/mail/% | C: 001 LIST "" ~/mail/% | |||
| (See also "Reference Names in the LIST Command" below.) | (See also "Reference Names in the LIST Command" below.) | |||
| 3.4.8. Creating Special-Use Mailboxes | 3.4.8. Creating Special-Use Mailboxes | |||
| skipping to change at page 16, line 44 ¶ | skipping to change at page 17, line 24 ¶ | |||
| interoperability problems with this practice: | interoperability problems with this practice: | |||
| 1. different clients may use different names for mailboxes with | 1. different clients may use different names for mailboxes with | |||
| similar functions (such as "Trash" and "Deleted"), or may manage the | similar functions (such as "Trash" and "Deleted"), or may manage the | |||
| same mailboxes in different ways, causing problems if a user switches | same mailboxes in different ways, causing problems if a user switches | |||
| between clients and | between clients and | |||
| 2. there is no guarantee that the server will allow the creation of | 2. there is no guarantee that the server will allow the creation of | |||
| the desired mailbox. | the desired mailbox. | |||
| The client developer is, therefore, well advised to consider | The client developer is, therefore, well advised to consider | |||
| carefully the creation of any special-use mailboxes on the server, | carefully the creation of any special-use mailboxes on the server, | |||
| and, further, the client MUST NOT require such mailbox creation - | and, further, the client must not require such mailbox creation - | |||
| that is, if you do decide to do this, you MUST handle gracefully the | that is, if you do decide to do this, you must handle gracefully the | |||
| failure of the CREATE command and behave reasonably when your | failure of the CREATE command and behave reasonably when your | |||
| special-use mailboxes do not exist and can not be created. | special-use mailboxes do not exist and can not be created. | |||
| In addition, the client developer SHOULD provide a convenient way for | In addition, the client developer should provide a convenient way for | |||
| the user to select the names for any special-use mailboxes, allowing | the user to select the names for any special-use mailboxes, allowing | |||
| the user to make these names the same in all clients used and to put | the user to make these names the same in all clients used and to put | |||
| them where the user wants them. | them where the user wants them. | |||
| 3.4.9. Reference Names in the LIST Command | 3.4.9. Reference Names in the LIST Command | |||
| Many implementers of both clients and servers are confused by the | Many implementers of both clients and servers are confused by the | |||
| "reference name" on the LIST command. The reference name is intended | "reference name" on the LIST command. The reference name is intended | |||
| to be used in much the way a "cd" (change directory) command is used | to be used in much the way a "cd" (change directory) command is used | |||
| on Unix, PC DOS, Windows, and OS/2 systems. That is, the mailbox | on Unix, PC DOS, Windows, and OS/2 systems. That is, the mailbox | |||
| skipping to change at page 17, line 37 ¶ | skipping to change at page 18, line 15 ¶ | |||
| only to the user's personal mailboxes, or to some other limited set | only to the user's personal mailboxes, or to some other limited set | |||
| of files, making such file-system-like semantics less meaningful. | of files, making such file-system-like semantics less meaningful. | |||
| Third, because the IMAP spec leaves the interpretation of the | Third, because the IMAP spec leaves the interpretation of the | |||
| reference name as "implementation-dependent", in the past the various | reference name as "implementation-dependent", in the past the various | |||
| server implementations handled it in vastly differing ways. | server implementations handled it in vastly differing ways. | |||
| The following recommendations are the result of significant | The following recommendations are the result of significant | |||
| operational experience, and are intended to maximize | operational experience, and are intended to maximize | |||
| interoperability. | interoperability. | |||
| Server implementations MUST implement the reference argument in a way | Server implementations must implement the reference argument in a way | |||
| that matches the intended "change directory" operation as closely as | that matches the intended "change directory" operation as closely as | |||
| possible. As a minimum implementation, the reference argument may be | possible. As a minimum implementation, the reference argument may be | |||
| prepended to the mailbox name (while suppressing double delimiters; | prepended to the mailbox name (while suppressing double delimiters; | |||
| see the next paragraph). Even servers that do not provide a way to | see the next paragraph). Even servers that do not provide a way to | |||
| break out of the current hierarchy (see "breakout facility" below) | break out of the current hierarchy (see "breakout facility" below) | |||
| MUST provide a reasonable implementation of the reference argument, | must provide a reasonable implementation of the reference argument, | |||
| as described here, so that they will interoperate with clients that | as described here, so that they will interoperate with clients that | |||
| use it. | use it. | |||
| Server implementations that prepend the reference argument to the | Server implementations that prepend the reference argument to the | |||
| mailbox name SHOULD insert a hierarchy delimiter between them, and | mailbox name should insert a hierarchy delimiter between them, and | |||
| MUST NOT insert a second if one is already present: | must not insert a second if one is already present: | |||
| C: A001 LIST ABC DEF | C: A001 LIST ABC DEF | |||
| S: * LIST () "/" ABC/DEF <=== SHOULD do this | S: * LIST () "/" ABC/DEF <=== should do this | |||
| S: A001 OK done | S: A001 OK done | |||
| C: A002 LIST ABC/ /DEF | C: A002 LIST ABC/ /DEF | |||
| S: * LIST () "/" ABC//DEF <=== MUST NOT do this | S: * LIST () "/" ABC//DEF <=== must not do this | |||
| S: A002 OK done | S: A002 OK done | |||
| On clients, the reference argument is chiefly used to implement a | On clients, the reference argument is chiefly used to implement a | |||
| "breakout facility", wherein the user may directly access a mailbox | "breakout facility", wherein the user may directly access a mailbox | |||
| outside the "current directory" hierarchy. Client implementations | outside the "current directory" hierarchy. Client implementations | |||
| SHOULD have an operational mode that does not use the reference | should have an operational mode that does not use the reference | |||
| argument. This is to interoperate with older servers that did not | argument. This is to interoperate with older servers that did not | |||
| implement the reference argument properly. While it's a good idea to | implement the reference argument properly. While it's a good idea to | |||
| give the user access to a breakout facility, clients that do not | give the user access to a breakout facility, clients that do not | |||
| intend to do so SHOULD NOT use the reference argument at all. | intend to do so should not use the reference argument at all. | |||
| Client implementations SHOULD always place a trailing hierarchy | Client implementations should always place a trailing hierarchy | |||
| delimiter on the reference argument. This is because some servers | delimiter on the reference argument. This is because some servers | |||
| prepend the reference argument to the mailbox name without inserting | prepend the reference argument to the mailbox name without inserting | |||
| a hierarchy delimiter, while others do insert a hierarchy delimiter | a hierarchy delimiter, while others do insert a hierarchy delimiter | |||
| if one is not already present. A client that puts the delimiter in | if one is not already present. A client that puts the delimiter in | |||
| will work with both varieties of server. | will work with both varieties of server. | |||
| Client implementations that implement a breakout facility SHOULD | Client implementations that implement a breakout facility should | |||
| allow the user to choose whether or not to use a leading hierarchy | allow the user to choose whether or not to use a leading hierarchy | |||
| delimiter on the mailbox argument. This is because the handling of a | delimiter on the mailbox argument. This is because the handling of a | |||
| leading mailbox hierarchy delimiter also varies from server to | leading mailbox hierarchy delimiter also varies from server to | |||
| server, and even between different mailstores on the same server. In | server, and even between different mailstores on the same server. In | |||
| some cases, a leading hierarchy delimiter means "discard the | some cases, a leading hierarchy delimiter means "discard the | |||
| reference argument" (implementing the intended breakout facility), | reference argument" (implementing the intended breakout facility), | |||
| thus: | thus: | |||
| C: A001 LIST ABC/ /DEF | C: A001 LIST ABC/ /DEF | |||
| S: * LIST () "/" /DEF | S: * LIST () "/" /DEF | |||
| S: A001 OK done | S: A001 OK done | |||
| In other cases, however, the two are catenated and the extra | In other cases, however, the two are catenated and the extra | |||
| hierarchy delimiter is discarded, thus: | hierarchy delimiter is discarded, thus: | |||
| C: A001 LIST ABC/ /DEF | C: A001 LIST ABC/ /DEF | |||
| S: * LIST () "/" ABC/DEF | S: * LIST () "/" ABC/DEF | |||
| S: A001 OK done | S: A001 OK done | |||
| Client implementations MUST NOT assume that the server supports a | Client implementations must not assume that the server supports a | |||
| breakout facility, but MAY provide a way for the user to use one if | breakout facility, but may provide a way for the user to use one if | |||
| it is available. Any breakout facility should be exported to the | it is available. Any breakout facility should be exported to the | |||
| user interface. Note that there may be other "breakout" characters | user interface. Note that there may be other "breakout" characters | |||
| besides the hierarchy delimiter (for instance, UNIX filesystem | besides the hierarchy delimiter (for instance, UNIX filesystem | |||
| servers are likely to use a leading "~" as well), and that their | servers are likely to use a leading "~" as well), and that their | |||
| interpretation is server-dependent. | interpretation is server-dependent. | |||
| 3.4.12. Mailbox Hierarchy Delimiters | 3.4.12. Mailbox Hierarchy Delimiters | |||
| The server's selection of what to use as a mailbox hierarchy | The server's selection of what to use as a mailbox hierarchy | |||
| delimiter is a difficult one, involving several issues: What | delimiter is a difficult one, involving several issues: What | |||
| characters do users expect to see? What characters can they enter | characters do users expect to see? What characters can they enter | |||
| for a hierarchy delimiter if it is desired (or required) that the | for a hierarchy delimiter if it is desired (or required) that the | |||
| user enter it? What character can be used for the hierarchy | user enter it? What character can be used for the hierarchy | |||
| delimiter, noting that the chosen character can not otherwise be used | delimiter, noting that the chosen character can not otherwise be used | |||
| in the mailbox name? | in the mailbox name? | |||
| Because some interfaces show users the hierarchy delimiters or allow | Because some interfaces show users the hierarchy delimiters or allow | |||
| users to enter qualified mailbox names containing them, server | users to enter qualified mailbox names containing them, server | |||
| implementations SHOULD use delimiter characters that users generally | implementations should use delimiter characters that users generally | |||
| expect to see as name separators. The most common characters used | expect to see as name separators. The most common characters used | |||
| for this are "/" (as in Unix file names), "\" (as in OS/2 and Windows | for this are "/" (as in Unix file names), "\" (as in OS/2 and Windows | |||
| file names), and "." (as in news groups). There is little to choose | file names), and "." (as in news groups). There is little to choose | |||
| among these apart from what users may expect or what is dictated by | among these apart from what users may expect or what is dictated by | |||
| the underlying file system, if any. One consideration about using | the underlying file system, if any. One consideration about using | |||
| "\" is that it's also a special character in the IMAP protocol. | "\" is that it's also a special character in the IMAP protocol. | |||
| While the use of other hierarchy delimiter characters is permissible, | While the use of other hierarchy delimiter characters is permissible, | |||
| A DESIGNER IS WELL ADVISED TO STAY WITH ONE FROM THIS SET unless the | A DESIGNER IS WELL ADVISED TO STAY WITH ONE FROM THIS SET unless the | |||
| server is intended for special purposes only. Implementers might be | server is intended for special purposes only. Implementers might be | |||
| thinking about using characters such as "-", "_", ";", "&", "#", "@", | thinking about using characters such as "-", "_", ";", "&", "#", "@", | |||
| and "!", but they should be aware of the surprise to the user as well | and "!", but they should be aware of the surprise to the user as well | |||
| as of the effect on URLs and other external specifications (since | as of the effect on URLs and other external specifications (since | |||
| some of these characters have special meanings there). Also, a | some of these characters have special meanings there). Also, a | |||
| server that uses "\" (and clients of such a server) MUST remember to | server that uses "\" (and clients of such a server) must remember to | |||
| escape that character in quoted strings or to send literals instead. | escape that character in quoted strings or to send literals instead. | |||
| Literals are recommended over escaped characters in quoted strings in | Literals are recommended over escaped characters in quoted strings in | |||
| order to maintain compatibility with older IMAP versions that did not | order to maintain compatibility with older IMAP versions that did not | |||
| allow escaped characters in quoted strings (but check the grammar to | allow escaped characters in quoted strings (but check the grammar to | |||
| see where literals are allowed): | see where literals are allowed): | |||
| C: 001 LIST "" {13} | C: 001 LIST "" {13} | |||
| S: + send literal | S: + send literal | |||
| C: this\%\%\%\h* | C: this\%\%\%\h* | |||
| S: * LIST () "\\" {27} | S: * LIST () "\\" {27} | |||
| S: this\is\a\mailbox\hierarchy | S: this\is\a\mailbox\hierarchy | |||
| S: 001 OK LIST complete | S: 001 OK LIST complete | |||
| In any case, a server SHOULD NOT use normal alpha-numeric characters | In any case, a server should not use normal alpha-numeric characters | |||
| (such as "X" or "0") as delimiters; a user would be very surprised to | (such as "X" or "0") as delimiters; a user would be very surprised to | |||
| find that "EXPENDITURES" actually represented a two-level hierarchy. | find that "EXPENDITURES" actually represented a two-level hierarchy. | |||
| And a server SHOULD NOT use characters that are non-printable or | And a server should not use characters that are non-printable or | |||
| difficult or impossible to enter on a standard US keyboard. Control | difficult or impossible to enter on a standard US keyboard. Control | |||
| characters, box-drawing characters, and characters from non-US | characters, box-drawing characters, and characters from non-US | |||
| alphabets fit into this category. Their use presents | alphabets fit into this category. Their use presents | |||
| interoperability problems that are best avoided. | interoperability problems that are best avoided. | |||
| The UTF-7 encoding of mailbox names also raises questions about what | The UTF-7 encoding of mailbox names also raises questions about what | |||
| to do with the hierarchy delimiters in encoded names: do we encode | to do with the hierarchy delimiters in encoded names: do we encode | |||
| each hierarchy level and separate them with delimiters, or do we | each hierarchy level and separate them with delimiters, or do we | |||
| encode the fully qualified name, delimiters and all? The answer for | encode the fully qualified name, delimiters and all? The answer for | |||
| IMAP is the former: encode each hierarchy level separately, and | IMAP is the former: encode each hierarchy level separately, and | |||
| insert delimiters between. This makes it particularly important not | insert delimiters between. This makes it particularly important not | |||
| to use as a hierarchy delimiter a character that might cause | to use as a hierarchy delimiter a character that might cause | |||
| confusion with IMAP's modified UTF-7 [UTF-7 and RFC-2060] encoding. | confusion with IMAP's modified UTF-7 [UTF-7 and RFC-2060] encoding. | |||
| To repeat: a server SHOULD use "/", "\", or "." as its hierarchy | To repeat: a server should use "/", "\", or "." as its hierarchy | |||
| delimiter. The use of any other character is likely to cause | delimiter. The use of any other character is likely to cause | |||
| problems and is STRONGLY DISCOURAGED. | problems and is STRONGLY DISCOURAGED. | |||
| 3.4.11. ALERT Response Codes | 3.4.11. ALERT Response Codes | |||
| The protocol spec is very clear on the matter of what to do with | The protocol spec is very clear on the matter of what to do with | |||
| ALERT response codes, and yet there are many clients that violate it | ALERT response codes, and yet there are many clients that violate it | |||
| so it needs to be said anyway: "The human-readable text contains a | so it needs to be said anyway: "The human-readable text contains a | |||
| special alert that MUST be presented to the user in a fashion that | special alert that must be presented to the user in a fashion that | |||
| calls the user's attention to the message." That should be clear | calls the user's attention to the message." That should be clear | |||
| enough, but I'll repeat it here: Clients MUST present ALERT text | enough, but I'll repeat it here: Clients must present ALERT text | |||
| clearly to the user. | clearly to the user. | |||
| 3.4.12. Deleting Mailboxes | 3.4.12. Deleting Mailboxes | |||
| The protocol does not guarantee that a client may delete a mailbox | The protocol does not guarantee that a client may delete a mailbox | |||
| that is not empty, though on some servers it is permissible and is, | that is not empty, though on some servers it is permissible and is, | |||
| in fact, much faster than the alternative or deleting all the | in fact, much faster than the alternative or deleting all the | |||
| messages from the client. If the client chooses to try to take | messages from the client. If the client chooses to try to take | |||
| advantage of this possibility it MUST be prepared to use the other | advantage of this possibility it must be prepared to use the other | |||
| method in the even that the more convenient one fails. Further, a | method in the even that the more convenient one fails. Further, a | |||
| client SHOULD NOT try to delete the mailbox that it has selected, but | client should not try to delete the mailbox that it has selected, but | |||
| should first close that mailbox; some servers do not permit the | should first close that mailbox; some servers do not permit the | |||
| deletion of the selected mailbox. | deletion of the selected mailbox. | |||
| That said, a server SHOULD permit the deletion of a non-empty | That said, a server should permit the deletion of a non-empty | |||
| mailbox; there's little reason to pass this work on to the client. | mailbox; there's little reason to pass this work on to the client. | |||
| Moreover, forbidding this prevents the deletion of a mailbox that for | Moreover, forbidding this prevents the deletion of a mailbox that for | |||
| some reason can not be opened or expunged, leading to possible | some reason can not be opened or expunged, leading to possible | |||
| denial-of-service problems. | denial-of-service problems. | |||
| Example: | Example: | |||
| [User tells the client to delete mailbox BANANA, which is | [User tells the client to delete mailbox BANANA, which is | |||
| currently selected...] | currently selected...] | |||
| C: 008 CLOSE | C: 008 CLOSE | |||
| S: 008 OK done | S: 008 OK done | |||
| skipping to change at page 22, line 37 ¶ | skipping to change at page 23, line 15 ¶ | |||
| 6. Author's Address | 6. Author's Address | |||
| Barry Leiba | Barry Leiba | |||
| IBM T.J. Watson Research Center | IBM T.J. Watson Research Center | |||
| 30 Saw Mill River Road | 30 Saw Mill River Road | |||
| Hawthorne, NY 10532 | Hawthorne, NY 10532 | |||
| Phone: 1-914-784-7941 | Phone: 1-914-784-7941 | |||
| Email: leiba@watson.ibm.com | Email: leiba@watson.ibm.com | |||
| This document will expire at the end of October 1999. | This document will expire at the end of January 2000. | |||
| End of changes. 80 change blocks. | ||||
| 98 lines changed or deleted | 121 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/ | ||||