1.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
     1.2 +++ b/docs/rfc/rfc2177.txt	Mon Sep 14 15:17:45 2009 +0900
     1.3 @@ -0,0 +1,227 @@
     1.4 +
     1.5 +
     1.6 +
     1.7 +
     1.8 +
     1.9 +
    1.10 +Network Working Group                                           B. Leiba
    1.11 +Request for Comments: 2177               IBM T.J. Watson Research Center
    1.12 +Category: Standards Track                                      June 1997
    1.13 +
    1.14 +
    1.15 +                           IMAP4 IDLE command
    1.16 +
    1.17 +Status of this Memo
    1.18 +
    1.19 +   This document specifies an Internet standards track protocol for the
    1.20 +   Internet community, and requests discussion and suggestions for
    1.21 +   improvements.  Please refer to the current edition of the "Internet
    1.22 +   Official Protocol Standards" (STD 1) for the standardization state
    1.23 +   and status of this protocol.  Distribution of this memo is unlimited.
    1.24 +
    1.25 +1.   Abstract
    1.26 +
    1.27 +   The Internet Message Access Protocol [IMAP4] requires a client to
    1.28 +   poll the server for changes to the selected mailbox (new mail,
    1.29 +   deletions).  It's often more desirable to have the server transmit
    1.30 +   updates to the client in real time.  This allows a user to see new
    1.31 +   mail immediately.  It also helps some real-time applications based on
    1.32 +   IMAP, which might otherwise need to poll extremely often (such as
    1.33 +   every few seconds).  (While the spec actually does allow a server to
    1.34 +   push EXISTS responses aysynchronously, a client can't expect this
    1.35 +   behaviour and must poll.)
    1.36 +
    1.37 +   This document specifies the syntax of an IDLE command, which will
    1.38 +   allow a client to tell the server that it's ready to accept such
    1.39 +   real-time updates.
    1.40 +
    1.41 +2.   Conventions Used in this Document
    1.42 +
    1.43 +   In examples, "C:" and "S:" indicate lines sent by the client and
    1.44 +   server respectively.
    1.45 +
    1.46 +   The key words "MUST", "MUST NOT", "SHOULD", "SHOULD NOT", and "MAY"
    1.47 +   in this document are to be interpreted as described in RFC 2060
    1.48 +   [IMAP4].
    1.49 +
    1.50 +3.   Specification
    1.51 +
    1.52 +   IDLE Command
    1.53 +
    1.54 +   Arguments:  none
    1.55 +
    1.56 +   Responses:  continuation data will be requested; the client sends
    1.57 +               the continuation data "DONE" to end the command
    1.58 +
    1.59 +
    1.60 +
    1.61 +Leiba                       Standards Track                     [Page 1]
    1.62 +
    1.63 +RFC 2177                   IMAP4 IDLE command                  June 1997
    1.64 +
    1.65 +
    1.66 +
    1.67 +   Result:     OK - IDLE completed after client sent "DONE"
    1.68 +               NO - failure: the server will not allow the IDLE
    1.69 +                    command at this time
    1.70 +              BAD - command unknown or arguments invalid
    1.71 +
    1.72 +   The IDLE command may be used with any IMAP4 server implementation
    1.73 +   that returns "IDLE" as one of the supported capabilities to the
    1.74 +   CAPABILITY command.  If the server does not advertise the IDLE
    1.75 +   capability, the client MUST NOT use the IDLE command and must poll
    1.76 +   for mailbox updates.  In particular, the client MUST continue to be
    1.77 +   able to accept unsolicited untagged responses to ANY command, as
    1.78 +   specified in the base IMAP specification.
    1.79 +
    1.80 +   The IDLE command is sent from the client to the server when the
    1.81 +   client is ready to accept unsolicited mailbox update messages.  The
    1.82 +   server requests a response to the IDLE command using the continuation
    1.83 +   ("+") response.  The IDLE command remains active until the client
    1.84 +   responds to the continuation, and as long as an IDLE command is
    1.85 +   active, the server is now free to send untagged EXISTS, EXPUNGE, and
    1.86 +   other messages at any time.
    1.87 +
    1.88 +   The IDLE command is terminated by the receipt of a "DONE"
    1.89 +   continuation from the client; such response satisfies the server's
    1.90 +   continuation request.  At that point, the server MAY send any
    1.91 +   remaining queued untagged responses and then MUST immediately send
    1.92 +   the tagged response to the IDLE command and prepare to process other
    1.93 +   commands. As in the base specification, the processing of any new
    1.94 +   command may cause the sending of unsolicited untagged responses,
    1.95 +   subject to the ambiguity limitations.  The client MUST NOT send a
    1.96 +   command while the server is waiting for the DONE, since the server
    1.97 +   will not be able to distinguish a command from a continuation.
    1.98 +
    1.99 +   The server MAY consider a client inactive if it has an IDLE command
   1.100 +   running, and if such a server has an inactivity timeout it MAY log
   1.101 +   the client off implicitly at the end of its timeout period.  Because
   1.102 +   of that, clients using IDLE are advised to terminate the IDLE and
   1.103 +   re-issue it at least every 29 minutes to avoid being logged off.
   1.104 +   This still allows a client to receive immediate mailbox updates even
   1.105 +   though it need only "poll" at half hour intervals.
   1.106 +
   1.107 +
   1.108 +
   1.109 +
   1.110 +
   1.111 +
   1.112 +
   1.113 +
   1.114 +
   1.115 +
   1.116 +
   1.117 +Leiba                       Standards Track                     [Page 2]
   1.118 +
   1.119 +RFC 2177                   IMAP4 IDLE command                  June 1997
   1.120 +
   1.121 +
   1.122 +   Example:    C: A001 SELECT INBOX
   1.123 +               S: * FLAGS (Deleted Seen)
   1.124 +               S: * 3 EXISTS
   1.125 +               S: * 0 RECENT
   1.126 +               S: * OK [UIDVALIDITY 1]
   1.127 +               S: A001 OK SELECT completed
   1.128 +               C: A002 IDLE
   1.129 +               S: + idling
   1.130 +               ...time passes; new mail arrives...
   1.131 +               S: * 4 EXISTS
   1.132 +               C: DONE
   1.133 +               S: A002 OK IDLE terminated
   1.134 +               ...another client expunges message 2 now...
   1.135 +               C: A003 FETCH 4 ALL
   1.136 +               S: * 4 FETCH (...)
   1.137 +               S: A003 OK FETCH completed
   1.138 +               C: A004 IDLE
   1.139 +               S: * 2 EXPUNGE
   1.140 +               S: * 3 EXISTS
   1.141 +               S: + idling
   1.142 +               ...time passes; another client expunges message 3...
   1.143 +               S: * 3 EXPUNGE
   1.144 +               S: * 2 EXISTS
   1.145 +               ...time passes; new mail arrives...
   1.146 +               S: * 3 EXISTS
   1.147 +               C: DONE
   1.148 +               S: A004 OK IDLE terminated
   1.149 +               C: A005 FETCH 3 ALL
   1.150 +               S: * 3 FETCH (...)
   1.151 +               S: A005 OK FETCH completed
   1.152 +               C: A006 IDLE
   1.153 +
   1.154 +4.   Formal Syntax
   1.155 +
   1.156 +   The following syntax specification uses the augmented Backus-Naur
   1.157 +   Form (BNF) notation as specified in [RFC-822] as modified by [IMAP4].
   1.158 +   Non-terminals referenced but not defined below are as defined by
   1.159 +   [IMAP4].
   1.160 +
   1.161 +   command_auth    ::= append / create / delete / examine / list / lsub /
   1.162 +                       rename / select / status / subscribe / unsubscribe
   1.163 +                       / idle
   1.164 +                       ;; Valid only in Authenticated or Selected state
   1.165 +
   1.166 +   idle            ::= "IDLE" CRLF "DONE"
   1.167 +
   1.168 +
   1.169 +
   1.170 +
   1.171 +
   1.172 +
   1.173 +Leiba                       Standards Track                     [Page 3]
   1.174 +
   1.175 +RFC 2177                   IMAP4 IDLE command                  June 1997
   1.176 +
   1.177 +
   1.178 +5.   References
   1.179 +
   1.180 +   [IMAP4] Crispin, M., "Internet Message Access Protocol - Version
   1.181 +   4rev1", RFC 2060, December 1996.
   1.182 +
   1.183 +6.   Security Considerations
   1.184 +
   1.185 +   There are no known security issues with this extension.
   1.186 +
   1.187 +7.   Author's Address
   1.188 +
   1.189 +   Barry Leiba
   1.190 +   IBM T.J. Watson Research Center
   1.191 +   30 Saw Mill River Road
   1.192 +   Hawthorne, NY  10532
   1.193 +
   1.194 +   Email: leiba@watson.ibm.com
   1.195 +
   1.196 +
   1.197 +
   1.198 +
   1.199 +
   1.200 +
   1.201 +
   1.202 +
   1.203 +
   1.204 +
   1.205 +
   1.206 +
   1.207 +
   1.208 +
   1.209 +
   1.210 +
   1.211 +
   1.212 +
   1.213 +
   1.214 +
   1.215 +
   1.216 +
   1.217 +
   1.218 +
   1.219 +
   1.220 +
   1.221 +
   1.222 +
   1.223 +
   1.224 +
   1.225 +
   1.226 +
   1.227 +
   1.228 +
   1.229 +Leiba                       Standards Track                     [Page 4]
   1.230 +