imapext-2007
view docs/commndmt.txt @ 0:ada5e610ab86
imap-2007e
| author | yuuji@gentei.org |
|---|---|
| date | Mon, 14 Sep 2009 15:17:45 +0900 |
| parents | |
| children |
line source
1 /* ========================================================================
2 * Copyright 1988-2006 University of Washington
3 *
4 * Licensed under the Apache License, Version 2.0 (the "License");
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
7 *
8 * http://www.apache.org/licenses/LICENSE-2.0
9 *
10 *
11 * ========================================================================
12 */
14 [I wrote this tongue-in-cheek, but there's a lot here that people who
15 build IMAP clients should take careful note. Most existing clients
16 violate at least one, generally several, of these commandments.
17 These are based on known user-visible problems that occur with various
18 commonly used clients. Put another way, behind each commandment is a
19 plethora of user (and server administrator) complaints caused by a
20 violator.]
22 Ten Commandments of How to Write an IMAP client
23 Mark Crispin
25 1. Thou shalt not assume that it is alright to open multiple IMAP
26 sessions selected on the same mailbox simultaneously, lest thou face
27 the righteous wrath of mail stores that doth not permit such access.
28 Instead, thou shalt labor mightily, even unto having to use thy brain
29 to thinketh the matter through, such that thy client use existing
30 sessions that are already open.
32 2. Thou shalt not abuse the STATUS command by using it to check for
33 new mail on a mailbox that you already have selected in an IMAP
34 session; for that session hath already told thou about new mail
35 without thy having to ask.
37 3. Thou shalt remember the 30 minute inactivity timeout, and remember
38 to speak to the IMAP server before that timeout expires. If thou
39 useth the IDLE command, thou shalt send DONE from the IDLE before 29
40 minutes hath passed, and issue a new IDLE. If thou maketh no use of
41 IDLE, then thou shalt send NOOP every few minutes, and the server
42 shalt tell you about new mail, and there will be much rejoicing in the
43 land.
45 4. Thou shalt not assume that all names are both the name of a mailbox
46 and the name of a upper level of hierarchy that contains mailboxes;
47 lest thou face the righteous wrath of mail stores in which a mailbox
48 is a file and a level of hierarchy is a directory. Thou shalt pay
49 diligent attention to the \NoSelect and \NoInferiors flags, so that
50 your users may praise you with great praise.
52 5. Thou shalt learn and understand the unique features of IMAP, such
53 as the unsolicited data model, the strict ascending rule of UIDs, how
54 UIDs map to sequence numbers, the ENVELOPE and BODYSTRUCTURE
55 structures; so that thou may use the IMAP protocol effectively. For a
56 POP client hacked to babble IMAP protocol is still no more than a POP
57 client.
59 6. Thou shalt remember untagged data sent by the server, and when thou
60 needest data thou shalt consult your memory before asking the server.
61 For those who must analyze thy protocol transactions are weak of
62 stomach, and are likely to lose their recent meal should they see thou
63 repeatedly re-fetch static data.
65 7. Thou shalt labor with great effort to work within the IMAP
66 deleted/expunge model, even if thy own model is that of a trashcan;
67 for interoperability is paramount and a trashcan model can be done
68 entirely in the user interface.
70 8. Thou shalt not fear to open multiple IMAP sessions to the server;
71 but thou shalt use this technique with wisdom. For verily it is true;
72 if thou doth desire to monitor continuously five mailboxes for new
73 mail, it is better to have five IMAP sessions continuously open on the
74 mailboxes. It is generally not good to do a succession of five SELECT
75 or STATUS commands on a periodic basis; and it is truly wretched to
76 open and close five sessions to do a STATUS or SELECT on a periodic
77 basis. The cost of opening and closing a session is great, especially
78 if that session is SSL/TLS protected; and the cost of a STATUS or
79 SELECT can also be great. By comparison, the cost of an open session
80 doing an IDLE or getting a NOOP every few minutes is small. Great
81 praise shall be given to thy wisdom in doing what is less costly
82 instead of "common sense."
84 9. Thou shalt not abuse subscriptions, for verily the LIST command is
85 the proper way to discover mailboxes on the server. Thou shalt not
86 subscribe names to the user's subscription list without explicit
87 instructions from the user; nor shalt thou assume that only subscribed
88 names are valid. Rather, thou shalt treat subscribed names as akin to
89 a bookmarks, or perhaps akin to how Windows shows the "My Documents"
90 folder -- a set of names that are separate from the hierarchy, for
91 they are such.
93 10. Thou shalt use the LIST "*" wildcard only with great care. If
94 thou doth not fully comprehend the danger of "*", thou shalt use only
95 "%" and forget about the existance of "*".
97 Honor these commandments, and keep them holy in thy heart, so that thy
98 users shalt maximize their pleasure, and the server administrators
99 shalt sing thy praises and recommend thy work as a model for others to
100 emulate.