Protocol Specification for "eximstate" 
======================================

The protocol used for "exim state" is loosely based around the SMTP protocol
defined in RFC 2821 (which superceded RFC 821). Some of the text from RFC 2821
has been reproduced below under the terms of its copyright notice.

Copyright (C) Claranet UK Ltd. (2002) by Ollie Cook.  All Rights Reserved.
$Id: PROTOCOL,v 1.2 2002/04/21 14:03:43 ollie Exp $

==========================================================================

1.    Commands
--------------

1.1.  General Command Semantics and Syntax
------------------------------------------

  Commands are transmitted in "lines".  Lines consist of zero or more data
  characters terminated by the sequence ASCII character "CR" (hex value
  0D) followed immediately by ASCII character "LF" (hex value 0A).
  This termination sequence is denoted as <CRLF> in this document.

  The space character is represented as <SP> in this document.

  Commands are character strings terminated by <CRLF>. The commands must
  consist of alphabetic characters, terminated by <SP> if additional
  arguments follow the command, or by <CRLF> if there are no arguments.

1.2.  HELO
----------

  When the client connects to the server, it identifies itself using the HELO
  command. The argument is used by the daemon as a unique key for the storage
  of the client data. No two clients should identify themselves with the same
  argument.

  It is suggested that the argument be the canonical hostname of the client
  host.

  Syntax:

    HELO <SP> [identifier] <CRLF>

1.3.  UPDATE
------------

  This command is used to cause the daemon to store new data from the client
  about the size of the mail queue on the client host at a particular time.

  The time is specified as Unix epoch time.

  Syntax:

    UPDATE <SP> [timestamp] : [total messages] : [frozen messages] <CRLF>

1.4.  QUIT
----------

  When the client wants to terminate its connection to the server is sends
  this command with no arguments.

  Syntax:

    QUIT <CRLF>

2.    Command Responses
-----------------------

  The server will respond to each command from the client with a one line
  response. The format of the response is a three digit number (transmitted
  as three numeric characters) followed by some optional text.

  A client MUST determine what actions it may take from the response code
  only and not from the text.

  The first digit of the response code denotes the severity of the response:

     - 2yz   Positive completion reply
             The command was accepted and the requested action was taken.
     - 5yz   Negative completion reply
             The command was not accepted and the requested action was not taken.

  The second digit of the response code denotes the category of the response:

     - x0z   Syntax errors
     - x1z   Connection information
     - x2z   Transaction information

  The third digit's use is unspecified at this time.

2.1.   Connection Responses
---------------------------

     210 Communications channel open. Proceed.
     211 Closing connection.
     212 Closing connection due to timeout.

2.2.   Transaction Responses
----------------------------

     220 Database updated. Information correctly stored.
     221 Hello %s. Continue
     520 Database update failed.

2.3.   Errors
-------------

     500 Unrecognised format of UPDATE command. Closing connection.
     500 Unrecognised format of HELO command. Closing connection.
     501 Unknown command (%s). Closing connection.          
     502 Internal error. See server logs.
             
--------------------------------------------------------------------------

Full Copyright Statement required due to reproduction of RFC 2821:

   Copyright (C) The Internet Society (2001).  All Rights Reserved.

   This document and translations of it may be copied and furnished to
   others, and derivative works that comment on or otherwise explain it
   or assist in its implementation may be prepared, copied, published
   and distributed, in whole or in part, without restriction of any
   kind, provided that the above copyright notice and this paragraph are
   included on all such copies and derivative works.  However, this
   document itself may not be modified in any way, such as by removing
   the copyright notice or references to the Internet Society or other
   Internet organizations, except as needed for the purpose of
   developing Internet standards in which case the procedures for
   copyrights defined in the Internet Standards process must be
   followed, or as required to translate it into languages other than
   English.

   The limited permissions granted above are perpetual and will not be
   revoked by the Internet Society or its successors or assigns.

   This document and the information contained herein is provided on an
   "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING
   TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING
   BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION
   HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF
   MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
