1.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
     1.2 +++ b/docs/commndmt.txt	Mon Sep 14 15:17:45 2009 +0900
     1.3 @@ -0,0 +1,101 @@
     1.4 +/* ========================================================================
     1.5 + * Copyright 1988-2006 University of Washington
     1.6 + *
     1.7 + * Licensed under the Apache License, Version 2.0 (the "License");
     1.8 + * you may not use this file except in compliance with the License.
     1.9 + * You may obtain a copy of the License at
    1.10 + *
    1.11 + *     http://www.apache.org/licenses/LICENSE-2.0
    1.12 + *
    1.13 + * 
    1.14 + * ========================================================================
    1.15 + */
    1.16 +
    1.17 +[I wrote this tongue-in-cheek, but there's a lot here that people who
    1.18 + build IMAP clients should take careful note.  Most existing clients
    1.19 + violate at least one, generally several, of these commandments.
    1.20 + These are based on known user-visible problems that occur with various
    1.21 + commonly used clients.  Put another way, behind each commandment is a
    1.22 + plethora of user (and server administrator) complaints caused by a
    1.23 + violator.]
    1.24 +
    1.25 +	   Ten Commandments of How to Write an IMAP client
    1.26 +			     Mark Crispin
    1.27 +
    1.28 +1. Thou shalt not assume that it is alright to open multiple IMAP
    1.29 +sessions selected on the same mailbox simultaneously, lest thou face
    1.30 +the righteous wrath of mail stores that doth not permit such access.
    1.31 +Instead, thou shalt labor mightily, even unto having to use thy brain
    1.32 +to thinketh the matter through, such that thy client use existing
    1.33 +sessions that are already open.
    1.34 +
    1.35 +2. Thou shalt not abuse the STATUS command by using it to check for
    1.36 +new mail on a mailbox that you already have selected in an IMAP
    1.37 +session; for that session hath already told thou about new mail
    1.38 +without thy having to ask.
    1.39 +
    1.40 +3. Thou shalt remember the 30 minute inactivity timeout, and remember
    1.41 +to speak to the IMAP server before that timeout expires.  If thou
    1.42 +useth the IDLE command, thou shalt send DONE from the IDLE before 29
    1.43 +minutes hath passed, and issue a new IDLE.  If thou maketh no use of
    1.44 +IDLE, then thou shalt send NOOP every few minutes, and the server
    1.45 +shalt tell you about new mail, and there will be much rejoicing in the
    1.46 +land.
    1.47 +
    1.48 +4. Thou shalt not assume that all names are both the name of a mailbox
    1.49 +and the name of a upper level of hierarchy that contains mailboxes;
    1.50 +lest thou face the righteous wrath of mail stores in which a mailbox
    1.51 +is a file and a level of hierarchy is a directory.  Thou shalt pay
    1.52 +diligent attention to the \NoSelect and \NoInferiors flags, so that
    1.53 +your users may praise you with great praise.
    1.54 +
    1.55 +5. Thou shalt learn and understand the unique features of IMAP, such
    1.56 +as the unsolicited data model, the strict ascending rule of UIDs, how
    1.57 +UIDs map to sequence numbers, the ENVELOPE and BODYSTRUCTURE
    1.58 +structures; so that thou may use the IMAP protocol effectively.  For a
    1.59 +POP client hacked to babble IMAP protocol is still no more than a POP
    1.60 +client.
    1.61 +
    1.62 +6. Thou shalt remember untagged data sent by the server, and when thou
    1.63 +needest data thou shalt consult your memory before asking the server.
    1.64 +For those who must analyze thy protocol transactions are weak of
    1.65 +stomach, and are likely to lose their recent meal should they see thou
    1.66 +repeatedly re-fetch static data.
    1.67 +
    1.68 +7. Thou shalt labor with great effort to work within the IMAP
    1.69 +deleted/expunge model, even if thy own model is that of a trashcan;
    1.70 +for interoperability is paramount and a trashcan model can be done
    1.71 +entirely in the user interface.
    1.72 +
    1.73 +8. Thou shalt not fear to open multiple IMAP sessions to the server;
    1.74 +but thou shalt use this technique with wisdom.  For verily it is true;
    1.75 +if thou doth desire to monitor continuously five mailboxes for new
    1.76 +mail, it is better to have five IMAP sessions continuously open on the
    1.77 +mailboxes.  It is generally not good to do a succession of five SELECT
    1.78 +or STATUS commands on a periodic basis; and it is truly wretched to
    1.79 +open and close five sessions to do a STATUS or SELECT on a periodic
    1.80 +basis.  The cost of opening and closing a session is great, especially
    1.81 +if that session is SSL/TLS protected; and the cost of a STATUS or
    1.82 +SELECT can also be great.  By comparison, the cost of an open session
    1.83 +doing an IDLE or getting a NOOP every few minutes is small.  Great
    1.84 +praise shall be given to thy wisdom in doing what is less costly
    1.85 +instead of "common sense."
    1.86 +
    1.87 +9. Thou shalt not abuse subscriptions, for verily the LIST command is
    1.88 +the proper way to discover mailboxes on the server.  Thou shalt not
    1.89 +subscribe names to the user's subscription list without explicit
    1.90 +instructions from the user; nor shalt thou assume that only subscribed
    1.91 +names are valid.  Rather, thou shalt treat subscribed names as akin to
    1.92 +a bookmarks, or perhaps akin to how Windows shows the "My Documents"
    1.93 +folder -- a set of names that are separate from the hierarchy, for
    1.94 +they are such.
    1.95 +
    1.96 +10. Thou shalt use the LIST "*" wildcard only with great care.  If
    1.97 +thou doth not fully comprehend the danger of "*", thou shalt use only
    1.98 +"%" and forget about the existance of "*".
    1.99 +
   1.100 +Honor these commandments, and keep them holy in thy heart, so that thy
   1.101 +users shalt maximize their pleasure, and the server administrators
   1.102 +shalt sing thy praises and recommend thy work as a model for others to
   1.103 +emulate.
   1.104 +