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