diff options
Diffstat (limited to 'imap/docs/commndmt.txt')
-rw-r--r-- | imap/docs/commndmt.txt | 101 |
1 files changed, 101 insertions, 0 deletions
diff --git a/imap/docs/commndmt.txt b/imap/docs/commndmt.txt new file mode 100644 index 00000000..7fd9707b --- /dev/null +++ b/imap/docs/commndmt.txt @@ -0,0 +1,101 @@ +/* ======================================================================== + * Copyright 1988-2006 University of Washington + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * + * ======================================================================== + */ + +[I wrote this tongue-in-cheek, but there's a lot here that people who + build IMAP clients should take careful note. Most existing clients + violate at least one, generally several, of these commandments. + These are based on known user-visible problems that occur with various + commonly used clients. Put another way, behind each commandment is a + plethora of user (and server administrator) complaints caused by a + violator.] + + Ten Commandments of How to Write an IMAP client + Mark Crispin + +1. Thou shalt not assume that it is alright to open multiple IMAP +sessions selected on the same mailbox simultaneously, lest thou face +the righteous wrath of mail stores that doth not permit such access. +Instead, thou shalt labor mightily, even unto having to use thy brain +to thinketh the matter through, such that thy client use existing +sessions that are already open. + +2. Thou shalt not abuse the STATUS command by using it to check for +new mail on a mailbox that you already have selected in an IMAP +session; for that session hath already told thou about new mail +without thy having to ask. + +3. Thou shalt remember the 30 minute inactivity timeout, and remember +to speak to the IMAP server before that timeout expires. If thou +useth the IDLE command, thou shalt send DONE from the IDLE before 29 +minutes hath passed, and issue a new IDLE. If thou maketh no use of +IDLE, then thou shalt send NOOP every few minutes, and the server +shalt tell you about new mail, and there will be much rejoicing in the +land. + +4. Thou shalt not assume that all names are both the name of a mailbox +and the name of a upper level of hierarchy that contains mailboxes; +lest thou face the righteous wrath of mail stores in which a mailbox +is a file and a level of hierarchy is a directory. Thou shalt pay +diligent attention to the \NoSelect and \NoInferiors flags, so that +your users may praise you with great praise. + +5. Thou shalt learn and understand the unique features of IMAP, such +as the unsolicited data model, the strict ascending rule of UIDs, how +UIDs map to sequence numbers, the ENVELOPE and BODYSTRUCTURE +structures; so that thou may use the IMAP protocol effectively. For a +POP client hacked to babble IMAP protocol is still no more than a POP +client. + +6. Thou shalt remember untagged data sent by the server, and when thou +needest data thou shalt consult your memory before asking the server. +For those who must analyze thy protocol transactions are weak of +stomach, and are likely to lose their recent meal should they see thou +repeatedly re-fetch static data. + +7. Thou shalt labor with great effort to work within the IMAP +deleted/expunge model, even if thy own model is that of a trashcan; +for interoperability is paramount and a trashcan model can be done +entirely in the user interface. + +8. Thou shalt not fear to open multiple IMAP sessions to the server; +but thou shalt use this technique with wisdom. For verily it is true; +if thou doth desire to monitor continuously five mailboxes for new +mail, it is better to have five IMAP sessions continuously open on the +mailboxes. It is generally not good to do a succession of five SELECT +or STATUS commands on a periodic basis; and it is truly wretched to +open and close five sessions to do a STATUS or SELECT on a periodic +basis. The cost of opening and closing a session is great, especially +if that session is SSL/TLS protected; and the cost of a STATUS or +SELECT can also be great. By comparison, the cost of an open session +doing an IDLE or getting a NOOP every few minutes is small. Great +praise shall be given to thy wisdom in doing what is less costly +instead of "common sense." + +9. Thou shalt not abuse subscriptions, for verily the LIST command is +the proper way to discover mailboxes on the server. Thou shalt not +subscribe names to the user's subscription list without explicit +instructions from the user; nor shalt thou assume that only subscribed +names are valid. Rather, thou shalt treat subscribed names as akin to +a bookmarks, or perhaps akin to how Windows shows the "My Documents" +folder -- a set of names that are separate from the hierarchy, for +they are such. + +10. Thou shalt use the LIST "*" wildcard only with great care. If +thou doth not fully comprehend the danger of "*", thou shalt use only +"%" and forget about the existance of "*". + +Honor these commandments, and keep them holy in thy heart, so that thy +users shalt maximize their pleasure, and the server administrators +shalt sing thy praises and recommend thy work as a model for others to +emulate. + |