Control Interface Protocol
AweMUD Next Generation
Copyright (C) 2003  AwesomePlay Productions, Inc.
Sean Middleditch <elanthis@awemud.net>
-------------------------------------------------

1. Introduction
   ============

   The new control interface feature of AweMUD allows a program to open a
   connection to the MUD using a UNIX domain socket, and issuing commands to
   the running AweMUD server.  These commands can be anything imaginable that
   is added to the code.  The basic intent, however, is to offer administration
   capabilities without needing to connect as a player.  The interface can also
   allow scripts and applications to programmatically control AweMUD.  This
   requires an easily parsable protocol.

2. Basics
   ======

   The protocl is line based.  The protocol is client driven.  The server only
   outputs information in response to a client command, or upon initial
   connection.  Clients send commands to the server as a single line, and the
   server responds with one or more lines of text.

   The server may then send one or more lines of response.  Responses are
   either error messages or success messages.  Success messages may be preceded
   by data messages.

   Upon first connecting, the server will return either a single success
   message, or an error message.  In the case of an error response, the client
   is immediately disconnected.

   The tool awemud-ctrl (src/awemud-ctrl in the build directory) allows
   communications with the server for utilizing the CIP (Control Interface
   Protocol).  In order to enable the CIP mechanism, the server/control
   setting in the awemud.conf file must be un-commented-out.  If you use a
   different socket path than the default, you may pass the socket path to the
   awemud-ctrl utility as a command-line argument.

   The socket will by default only be usable by the user who started the
   AweMUD server.  Note that if you configure AweMUD to switch user/group IDs
   after startup, the CIP socket will *not* use the specified IDs, but the
   original ID (root being the only option in this case for most OSes).

3. Commands
   ========

   Once connected to the socket, commands may be issued.  A command is a
   string of text formatted onto a single line.  Commands are comprised of one
   or more words.  Each word is separated by one or more spaces.  Tabs do not
   separate words.  The \ (backslash) character will escape the following
   character.  A \n sequence is interpreted as a newline.  Any other escape
   sequence is taken as a literal.  (For example, \\ is interpreted as \, and
   \{ is interpreted as {.)  Finally, if an unescaped { (left curly bracket)
   character is found then all following spaces until the next unescaped }
   (right curly bracket) are considred part of the word.  A { found during a
   quote is interpreted as a normal character, as is a } found outside a
   quote.

   Words after the first are called parameters.  The parameters given to a
   command may vary depending on the exact parameters used.  If an incorrect
   number of parameters, or invalid values, are given to a command, it may
   return a BADPARAM error.

   Examples:
   command arg1 arg2 arg3
   command {this arg has spaces}
   command This\ is\ one\ arg
   command {This is a block of\ntext with a newline}
   command !@#\{\\ arg2

4. Responses
   =========

   A success or error message comes in the form of a plus (+) followed by an
   error code.  Error codes are single words formed of all uppercase
   characters.  Examples are OK, BADCOMMAND, NOTFOUND and BADPARAM.

   If the error code is OK, the message is a success message.  For any other
   error code, the message is a failure (error) message.

   An optional human-friendly string may followed the error code.  The message
   and the code are separated by a single space.  These messages are not
   intended to be machine parsed, but may be presented to users of utilities
   or applications that use the protocol.  (The messages are also useful to
   users utilizing the awemud-ctrl utility directly.)

   Examples:
   +NOACCESS You do not have permission to access this resource.
   +BADCOMMAND Command not found.
   +NOTFOUND
   +BADPARAM Improper parameters given for command.
   +OK
   +OK Password changed

   When a command is successful, but before it has sent the success response,
   it may send one or more data lines.  If a data line is received, a
   successful response is guaranteed.  The success response line is in this
   case used as an end marker for the data lines.

   Each data line is prefixed with a single dash (-).  All of the information
   after the asterik is part of the data.

   Data may come in several forms.  The two most common are arbitrary block
   form, and key/value form.  Arbitrary value form is just a series of lines of
   data with no particular format.  This might be used to echo log messages or
   other blocks of text.

   Key value form is given as a key name, followed by an equal sign (=),
   followed by data.

   It is up to the client to know which commands return which kinds of data (if
   any) on success.

   Examples:
   -This is an
   -arbitrary block
   -of text.
   +OK
   -KEY=some value
   -key2=another value
   -foo=bar
   +OK

5. Available Commands
   ==================

   newaccount
   ----------
     Adds a new account to the system.  The user, upon logging in, will enter
     character creation.  This can be used by web forms and such to create new
     accounts and allow the system to disable automatic new accounts.

     You can, after creating the account, use the chpass, chname, and chmail
     commands to set the account properties.

     The newaccount command takes a single argument which is a user name.

     Ex:
     addaccount bob
     +OK
     addaccount invalid-username
     +BADPARAM Invalid characters in account name

   build
   -----
     Returns the build date and time of the server as a success value.

     Ex:
     build
     -Jan  8 2004 19:20:03
     +OK

   chmail
   ------
     Change a user's email address.  The username and new mail address must be
     given as parameters.  If a username is given that does not exist, a
     NOTFOUND error is returned.

     Ex:
     chmail admin master@localhost.foo
     +OK Mail address changed
     chpass bogus weird@there.here
     +NOTFOUND

   chname
   ------
     Change a user's real name.  The username and new real name must be given
     as parameters.  If a username is given that does not exist, a NOTFOUND
     error is returned.

     Ex:
     chmail admin {The master}
     +OK Name changed
     chpass bogus Some random user
     +NOTFOUND

   chpass
   ------
     Change a user's password.  The username and new passphrase must be given
     as parameters.  If a username is given that does not exist, a NOTFOUND
     error is returned.

     Ex:
     chpass admin test
     +OK Password changed
     chpass bogus test
     +NOTFOUND

   disable
   -------
     Disables an account.  If an account is disabled, no one may login to
     the account.  Returns a NOTFOUND error if the account doesn't exist.

     Ex:
     disable admin
     +OK Account disabled

   enable
   ------
     Enables an account.  If an account is disabled, no one may login to the
     account.  Returns a NOTFOUND error if the account doesn't exist.

     Ex:
     enable admin
     +OK Account enabled

   pcount
   ------
     Returns the number of currently active players as a success value.

     Ex:
     players
     -23
     +OK

   quit
   ----
     Disconnects from the server.  Success message is given.

     Ex:
     quit
     +OK Farewell
     [disconnected from server]

   setmaxactive
   ------------
     Sets the maximum number of characters an account is allowed to have
     active at any given time.  The first paramater is the account name, and
     the second parameter is the active character limit.  Use a limit of zero
     (0) to set the limit to the default, as specified in the awemud.conf
     configuration file.  Returns a NOTFOUND error if the account doesn't
     exist.

     Ex:
     setmaxactive admin 2
     +OK Account updated

   setmaxchars
   -----------
     Sets the maximum number of characters an account is allowed to have.  The
     first paramater is the account name, and the second parameter is the
     character limit.  Use a limit of zero (0) to set the limit to the
     default, as specified in the awemud.conf configuration file.  Returns a
     NOTFOUND error if the account doesn't exist.

     Ex:
     setmaxchars admin 5
     +OK Account updated

   showaccount
   -----------
     Displays the details of an account.  Returns a NOTFOUND error if the
     account doesn't exist.

     Ex:
     showaccount admin
     -ID=admin
     -NAME=Administrator
     -EMAIL=awemud@localhost
     -MAXCHARS=3
     -MAXACTIVE=1
     -DISABLED=NO
     -CHARACTERS=Admin,Tester
     +OK

   shutdown
   --------
     Shuts down the server immediately.

     Ex:
     shutdown
     +OK Shutting down

   version
   -------
     Returns the current version of the server software as success value.

     Ex:
     version
     -0.21
     +OK

6. Standard Error Codes
   ====================

   BADCOMMAND
   ----------
     The command given does not exist, or is not recognized by the server.
     Double check that the command is spelled properly.

   BADPARAM
   --------
     The parameters given to the command are incorrect.  Check the
     documentation for the command to be sure you are sending the correct
     parameters.  The error message may provide more clues as to what exactly
     is wrong.

   DUPLICATE
   ---------
     A duplicate item was detected when duplicates are not allowed.  The error
     message will usually indicate what was duplicated.

   INTERNAL
   --------
     An internal error has occured.  The error message will usually indicate
     what has happened in further detail.

   NOACCESS
   --------
     You do not have access to the command, or one of its functions.  Another
     command to authenticate the connection may be needed before you can
     attempt the command or functionality.
