$Id: CSCP.spec.txt,v 1.1 2000/03/16 00:23:27 jmayer Exp $

0 Overview of states

	The set of states governing the modes of this protocol consists of:
		1 Identification
		2 Authentication
		3 Read-only
		4 Transaction (read/write)
		5 Status
		6 Actuator

	Depending on what state the connection is in, different commands
	are available.

	Legal state transitions:
		1 -> 2  KNOCK-KNOCK command
		2 -> 3  Upon successful completion of authentication
		3 -> 2  REAUTH command
		3 -> 4  BEGIN transaction command
		3 -> 5  CHECK transaction command
		4 -> 3  CANCEL transaction command
		4 -> 5  COMMIT transaction command
		5 -> 3  BG or CANCEL command, or automatic on txn completion
	
	The state machine always starts in the "1 Identification" state
	for all transactions, with the exception of event handlers.

	State 6 is a special state just used for communications with
	event handlers.


1 Identification state

	As soon as the SM accepts a new connection, the connection starts in
	the Identification state.  The server will do nothing until the client
	introduces itself.

	The client should immediately announce itself with a KNOCK-KNOCK
	command, to which CCE responds with it's announce message to signal 
	a successful identification.  If no KNOCK-KNOCK is received in 10
	seconds, CCE will silently close the connection in an additional 1/2 to 
	5 seconds.
	
	announce-msg ::= '2000' SP 'CCE' SP version-number 

	Example: 
		2000 CCE 1.0

1.1 Command: KNOCK-KNOCK

	This command does nothing more than tell CSCP to begin.  It is a mild
	measure to prevent random connections from guessing the connection type,
	and not much else.

	knock-knock-cmd ::= 'KNOCK-KNOCK'

2 Authentication state

	The authentication piece of the CCE protocol is very similar
	to the authentication protocol of CRAP.  The primary goal is to
	provide a mechanism for authenticating without having to transmit
	a plaintext password.

	Once in the authentication state, CCE will silently wait for the client
	to issue a CLIENTAUTH command.
	
	The following commands are available to the user in the Authentication 
	state:
		CLIENTAUTH	alert server of authtypes client knows about
		AUTH		respond to an authentication challenge
		AUTHTYPES	list authtypes server knows about
		BYE         disconnect
		HELP		list available commands

2.1 Command: CLIENTAUTH

	CLIENTAUTH is the mechanism whereby a connected client alerts the
	server that it is ready to authenticate, and the authtypes it
	can support.  The server will respond with a challenge, identifying
	the authtype selected, and a challenge string.
	
	Currently we support TYPE1 and NULL challenges, which are described 
	further in the AUTH command section.

	clientauth-cmd ::= 'CLIENTAUTH' SP authtype-list 
	clientauth-success-msg ::= challenge-msg
	clientath-failure-msg ::= '4100' SP 'NO COMMON AUTHENTICATION' 

	challenge-msg ::= '1100' SP 'CHALLENGE' SP authtype [SP authinfo]
	authtype ::= 'TYPE1' | 'NULL'
	authinfo ::= challenge-string
	challenge-string ::= string of base64-encoded data
	
	Example: (C = client, S = server)
		C: CLIENTAUTH TYPE1
		S: 2100 CHALLENGE TYPE1 lovDBBLEAcKsSmHkZ973+w
	
2.2 Command: AUTH

	Authenticate a user, once an authtype has been selected by the
	server.

	auth-cmd ::= 'AUTH' SP username SP auth-string 
	auth-success-msg ::= '2000' SP 'AUTHENTICATION SUCCESSFUL' 
	auth-failure-msg ::= '4000' SP 'AUTHENTICATION FAILED' 
	
	Currently we support the 'NULL' and 'TYPE1' authentication
	mechanisms.  'NULL' is merely plaintext passwords, and should not
	be used except for debugging.

	The following describes the 'TYPE1' authentication scheme :

	'username' is the username the client is attempting to authenticate
	as.
	
	'auth-string' is a string of base65-encoded data.
	
	The server compares 'auth-string' with the base64-encoded MD5 digest of
	a string created by concatenating the following information:

		- the challenge-string
		- a single space character
		- the username
		- a single space character
		- the user's password
		- a single space character
		- the challenge-string
		- a string consisting of 200 space characters (padding).
	
	If the auth-string matches this base64-encoded MD5 digest, then
	authentication is successful.  The server indicates that authentication
	was successful by emiting the auth-success-msg, and switches to the
	read state.
	
	If authentication was unsuccessful:
		1. the server waits some time between one-half and 3 seconds,
		2. the server emits an auth-failure-msg, and then
		3. the server waits for a CLIENTAUTH command.
	The server remains in the Authentication state.

2.3 Command: AUTHTYPES

	The AUTHTYPES command asks the server to enumerate the authentication 
	mechanisms it understands.

	authtypes-cmd ::= 'AUTHTYPES' 
	authtypes-success-msg ::= gen-success-msg SP authype-list 
	authtype-list ::= authtype [SP authtype-list]

2.4 Command: BYE

	The BYE command causes the server to reply with bye-msg, and then
	the server terminates the connection.  This command is valid at any
	phase of transaction.  Any uncommitted changes are abandoned
	(equivalent to the CANCEL command).
	
	bye-cmd ::= 'BYE' 
	bye-msg ::= '2999' SP 'GOODBYE' 

2.5 Command: HELP

	HELP lists all available commands for the current state.

	help-cmd ::= 'HELP' 
	help-info-msg ::= '1110' SP cmd SP params SP descr 
	help-msg ::= gen-success-msg SP num-cmds SP 'LISTED' 

2.6 Example

	'S' is server, 'c' is client.

	C: KNOCK-KNOCK
	S: 2000 CCE 1.0 OK
	C: CLIENTAUTH UNSUPPORTEDPROTO
	S: 4100 NO COMMON AUTHENTICATION
	C: AUTHTYPES
	S: 2010 TYPE1
	C: CLIENTAUTH TYPE1
	S: 1100 CHALLENGE TYPE1 uH8CjfHsOlPCXQOoW+KItA
	S: 2010 OK
	C: AUTH admin X+rIoavCuZeSUpmDcgU9+w==
	S: 4001 AUTHENTICATION FAILED
	C: CLIENTAUTH TYPE1
	S: 1100 CHALLENGE TYPE1 557vqFjeAtjncbCsLyt2sg
	S: 2010 OK
	C: AUTH admin lovDBBLEAcKsSmHkZ973+w
	S: 2001 AUTHENTICATION SUCCESSFUL
	C: BYE
	S: 2999 GOODBYE
	


3 Read state

	In read state, the server waits for a newline-delimited command,
	and then replies with zero or more "informational" response codes,
	and terminates with one "final" response code, indicating the
	success or failure of the command.  The read state can be
	transitioned to a "write" state (called transaction state) by the
	BEGIN command.

	The following commands are available in the read state, and the
	transaction state:

	  BYE        disconnect, abort transaction if not committed (sec 2.2)
	  HELP       list available commands (sec 2.2)
	  FIND       locate all objects in the system matching criteria
	  OIDOF      return the oid for an object in the object hierarchy
	  GET	       read a scalar property on an object
	  TYPE       get the data type for a property
	  LIST       read the oids from a object reference property
	  BEGIN      open a transaction
	  CHECK      get status code of a committed transaction
	  CLASSVER   retrieve the version of a class
	  STRUCTURE  retrieve the structure of a class
	  CLASSLIST  list classes the server has defined

	The following commands, while not truly 'read' commands, are
	available in the read or transaction state, and are therefore defined
	here.
	
	  DEFINE    define a new class (admin/root only)
	  UNDEFINE  remove a class from the system (admin/root only)
	  EXTEND    change an object's structure (admin/root only)
	  CLASSACL  allow/deny access to iinstantiate a class definition
	  TYPEDEF	define a new datatype
	  TYPEUNDEF undefine a datatype
	  TYPELIST  list defined datatypes

	The following commands are available in the read state, but not the
	transaction state:

	  REAUTH    re-initiate the authentication state
	
3.1 Command: FIND	

	Finds all objects that match 'criteria'.  Find will not loop, if
	object inheritance loops exist.
	
	find-cmd ::= 'FIND' SP criteria [SP 'FROM' oid] 
		     [SP 'REPORT' SP prop-list] 
	criteria ::= criterion | (criterion SP criteria)
	criterion ::= property [SP] '=' [SP] value
	prop-list ::= property | (property SP prop-list)

	find-info-msg ::= '1140' SP 'FOUND' oid [SP prop-val-list] 
	find-success-msg ::= gen-success-msg SP num-found SP 'FOUND' 
	find-failure-msg ::= gen-badcriteria-msg
	                 ::= gen-unknownobj-msg
	                 ::= '4140' SP 'BAD REPORT FORMAT' 
	
3.2 Command: OIDOF

	OIDOF translates a string describing the full path to an object
	into the object's oid.

	oidof-cmd ::= 'OIDOF' SP object-path 
	object-path ::= ('/') | ('/' list-item) | ('/' list-item object-path)
	list-item ::= property{criteria}
	
	oidof-success-msg ::= gen-success-msg SP oid
	oidof-failure-msg ::= '4150' SP 'AMBIGUOUS PATH' 
	                  ::= gen-unknownobj-msg
	                  ::= '4151' SP 'BAD PATH' 

3.3 Command: GET		

	Queries the value of a scalar property on object oid.

	get-cmd ::= 'GET' SP oid SP property 
	get-success-msg ::= gen-success-msg SP value
	get-failure-msg ::= gen-unknownobj-msg
	                ::= gen-unknownprop-msg

3.4 Command: TYPE

	Gets the data type, as known by the server, of an object property

	type-cmd ::= 'TYPE' SP oid SP property 
	type-success-msg ::= gen-success-msg SP type
	type-failure-msg ::= gen-unknownobj-msg
	                 ::= gen-unknownprop-msg

3.5 Command: LIST	

	Lists the objects referenced in an object's reference-list property.
	This command will always return the list in order.  LIST may return
	less than the requested number of entries (in the case of a LENGTH
	clause) if the list does not have that many items left.

	list-cmd ::= 'LIST' SP oid SP property [SP criteria] 
	             [SP 'START' SP num] [SP 'LENGTH' SP num]
			 [SP 'REPORT' SP prop-list]
	list-info-msg ::= '1220' SP oid SP classname 
	list-success-msg ::= gen-success-msg SP num SP 'LISTED' 
	list-failure-msg ::= gen-unknownobj-msg
	                 ::= gen-unknownlist-msg

3.6 Command: BEGIN

	Begin a transaction.  This creates a transaction-id which can be
	used to identify this transaction later.  BEGIN transitions the
	connection into the transaction state.  The only way to close this
	transaction is to issue a COMMIT or CANCEL command, issue the BYE
	command, or disconnect.  

	begin-cmd ::= 'BEGIN' [SP 'NOLOCK'] 
	begin-success-msg ::= gen-success-msg SP txnid
	begin-failure-msg ::= gen-locked-msg
	
3.7 Command: CHECK

	The CHECK command puts the command in the commit state, displaying 
	status info messages for a given transaction.  This behavior is 
	identical the info phase COMMIT command and follows the same 
	semantics and message formats. 

	check-cmd ::= 'CHECK' SP txnid 
	check-success-msg ::= gen-success-msg SP 'DONE'
	check-failure-msg ::= gen-unknowntxn-msg
	                  ::= gen-badtxn-msg

3.8 Command: CLASSVER

        Returns the version number of a class definition.

        classver-cmd ::= 'CLASSVER' SP classname 
        classver-success-msg ::= gen-success-msg SP version 
        classver-failure-msg ::= gen-unknownclass-msg

3.9 Command: STRUCTURE

	The STRUCTURE command returns the structure of an object in a
	format suitable for submission with DEFINE or EXTEND.

	structure-cmd ::= 'STRUCTURE' SP [oid | classname]
	structure-success-msg ::= gen-success-msg SP classname SP 'VER' 
				  SP version SP 'ISA' SP parentclass 'PROPS' 
				  property-list 
	structure-failure-cmd ::= gen-unknownobj-msg

3.10 Command: CLASSLIST

	Generates a list of classes defined on the server.

	classlist-cmd ::= 'CLASSLIST' 
	classlist-info-msg ::= '1330' SP classname 
	classlist-msg ::= gen-success-msg SP num SP 'CLASSES' 

3.11 Command: DEFINE

	DEFINE creates a new class in the system, optionally based on some
	other class, with an optional version defined, an optional public
	key defined, and an optional description string (512 bytes).  This
	command is restricted to root and admin users only.  By default,
	only root/admin is allowed to instantiate a class - see the
	CLASSACL command to change this.

	define-cmd ::= 'DEFINE' SP classname [SP 'VER' SP version]
	               [SP 'ISA' SP parentclass] 'PROPS' property-list 
	               [SP 'KEY' SP key] [SP 'DESCR' "description"] 

	property-list ::= property-def | ( property-def property-list )
	property-def ::= scalar-property-def | ref-property-def
	scalar-property-def ::= 'SCALAR' SP property-name SP 'TYPE' type
                                [ SP 'DEFAULT' SP value ]
	ref-property-def ::= 'REF' SP property-value SP 'CLASS' type

	define-success-msg ::= gen-success-msg SP 'DEFINED'
	define-failure-msg ::= '4290' SP 'CLASS EXISTS' 
	                   ::= gen-unknownclass-msg

3.12 Command: UNDEFINE

	The UNDEFINE command should almost never be used, except when
	cleaning up while uninstalling a 3d Party Developer package or 
	during software development.  This command is restricted to root
	and admin users only.  

	undefine-cmd ::= 'UNDEFINE' SP classname [ SP 'DESTROY' ] 
	undefine-success-msg ::= gen-success-msg SP 'UNDEFINED'
	undefine-failure-msg ::= gen-unknownclass-msg
	                     ::= '4300' SP 'SUBCLASSES EXIST'

	The 'DESTROY' option causes all object data of class 'classname'
	to be destroyed as well.  Otherwise, the 'classless' data is allowed
	to float until the next garbage collection.

3.13 Command: EXTEND

	EXTEND adds properties to a class.  If a signature is provided,
	it is used to validate that the command was signed by the creator
	of the object (which has a KEY stored in the DEFINE command).  If a
	key is found, but no signature is provided, EXTEND will fail.  This
	command is restricted to root and admin users only.

	extend-cmd ::= 'EXTEND' SP classname SP 'PROPS' SP property-list 
	               [SP 'SIGNATURE' SP signature] [SP 'VER' SP version] 
	extend-success-msg ::= gen-success-msg SP 'EXTENDED'
	extend-warning-msg ::= '3320' SP property 'PROPERTY REDEFINED' 
	extend-failure-msg ::= gen-unknownclass-msg
	                   ::= gen-badsig-msg

	property-list ::= property-def | ( property-def property-list )
	property-def ::= scalar-property-def | ref-property-def
	scalar-property-def ::= 'SCALAR' SP property-name SP 'TYPE' type
	ref-property-def ::= 'REF' SP property-value SP 'CLASS' type 

3.14 Command: CLASSACL

	This command allows or denies permission for a given entity to
	instantiate a class.  This is to protect actuators registered on
	the _NEW property from running on behalf of invalid users.  This
	command is restricted to root and admin users only.  Oid must be an
	object derived from 'Entity', just as in an ACL (see
	Security.Model.txt).

	classacl-cmd ::= 'CLASSACL' SP classname SP ['ALLOW' | 'DENY'] oid
	classacl-success-msg ::= gen-success-msg SP ['ALLOWED' | 'DENIED']
	                     ::= gen-noop-msg SP 'ALREADY' SP 
	                         ['ALLOWED' | 'DENIED']
	classacl-failure-msg ::= gen-unknownclass-msg
	                     ::= gen-unknownobjref-msg
	                     ::= gen-badval-msg SP 'WRONG CLASS TYPE'

3.15 Command: REAUTH

	Re-initiates the authentication state.  This allows client programs
	to assume different user capabilities without re-connecting.

	reauth-cmd ::= 'REAUTH'
	reauth-success-msg ::= gen-success-msg SP 'OK'

3.16 Command: TYPEDEF

	Defines a new data type for the system.  A new datatype may be
	defined to be either an internal type (such as 'int'), or any other
	definable type (such as 're:' or 'extern:').

	typedef-cmd ::= 'TYPEDEF' SP typename SP type
	typedef-success-msg ::= gen-success-msg SP 'DEFINED'
	typedef-failure-msg ::= gen-badval-msg
	                    ::= '4450' SP 'TYPE EXISTS'

3.17 Command: TYPEUNDEF

	Removes a data type from the system.  

	typeundef-cmd ::= 'TYPEUNDEF' SP typename
	typeundef-success-msg ::= gen-success-msg SP 'UNDEFINED'
	typeundef-failure-msg ::= '4460' SP 'UNKNOWN TYPE'

3.18 Command: TYPELIST

	Lists all types known to the system.

	typelist-cmd ::= 'TYPELIST'
	typelist-info-msg ::= '1470' SP typename SP type
	classlist-msg ::= gen-success-msg SP num SP 'TYPES' 

4 Transaction state

	In summary, valid commands in the transaction state consist of all
	commands in the read state, plus the following:

	  NEW	      create a new object
	  DESTROY   remove an object
	  SET	      set a scalar property on an object
	  UNSET     set a property to use the class default
	  TOUCH     set the changed flag on an object-property
	  LISTADD   add an oid to a list of object references
	  LISTRM    remove an oid from a list of object references
	  COMMIT    commit and actuates all changes
	  CANCEL    cancel a non-commited transaction and undoes changes
	  LOCK      attempt to lock an object
	  UNLOCK    attempt to unlock an object
	
4.1 Command: NEW		

	Creates a new object of class "classname", and automatically
	links it into the object-reference-list property specified
	by "oid" and "property."  If the object can not be linked
	into the obj-ref-list, the object can not be created.

	If successful, the NEW command returns a temporary handle to the 
	newly created object.  This handle can be used by the client 
	application to reference the object as if it were an oid.  The reason 
	for the handle is to defer creation of the actual object within the 
	system tree until COMMIT is issued.  

	When the object is created, by creator is added by default to the
	objects ALLOW lists (READ, WRITE, and CHMOD).

	new-cmd ::= 'NEW' SP classname SP oid SP property
	new-success-msg ::= gen-success-msg SP handle SP 'CREATED'
	new-failure-msg ::= gen-unknownclass-msg
			    ::= gen-unknownobj-msg
	                ::= gen-unknownlist-msg
	                ::= gen-badval-msg
	
	* Creates a NEW event in the transaction object.

4.2 Command: DESTROY	

	Destroys an object specified by an oid.
	
	destroy-cmd ::= 'DESTROY' SP oid 
	destroy-success-msg ::= gen-success-msg SP 'DESTROYED'
	destroy-failure-msg ::= gen-unknownobj-msg

	* Creates a DESTROY event in the transaction object.
	
4.3 Command: SET		

	Sets a scalar property value on object oid.

	set-cmd ::= 'SET' SP oid SP property SP value 
	set-success-msg ::= gen-success-msg SP 'SET'
	set-failure-msg ::= gen-unknownobj-msg
	                ::= gen-unknownprop-msg
	                ::= gen-badvalue-msg

	* Creates a SET event in the transaction object.

4.4 Command: UNSET

	Clears a scalar property value on object oid back to the
	"undefined" state (ie. use the class default).

	unset-cmd ::= 'UNSET' SP oid SP property 
	unset-success-msg ::= gen-success-msg SP 'UNSET'
	unset-failure-msg ::= gen-unknownobj-msg
				::= gen-unknownprop-msg

4.5 Command: TOUCH	

	Sets the 'changed' flag on an object property (scalar or ref)
	without actually changing it.

	touch-cmd ::= 'TOUCH' SP oid SP property 
	touch-success-msg ::= gen-success-msg SP 'TOUCHED'
	touch-failure-msg ::= gen-unknownobj-msg
	                  ::= gen-unknownprop-msg

	* Creates a SET event in the transaction object.

4.6 Command: LISTADD	

	Adds object 'newoid' into the list of object references
	denoted by oid.property.

	The 'BEFORE' or 'AFTER' attribute can be set to indicate
	the position in the object list at which the newoid should
	be inserted.  If no 'BEFORE' or 'AFTER' attribute is 
	specified, the object is appended to the end of the list.	

	listadd-cmd ::= 'LISTADD' SP oid SP property SP newoid 
	                [('BEFORE' | 'AFTER') SP oid2]

	listadd-success-msg ::= gen-success-msg SP 'ADDED'
	                    ::= gen-noop-msg SP 'ALREADY IN LIST'
	listadd-failure-msg ::= gen-unknownobj-msg
	                    ::= gen-unknownlist-msg
	                    ::= gen-unknownobjref-msg
	                    ::= gen-badval-msg
	
	* Creates a SET event in the transaction object.

4.7 Command: LISTRM	

	Removes object 'oid' from the list of object references
	denoted by listoid.property.

	listrm-cmd ::= 'LISTRM' SP listoid SP property SP oid
	listrm-success-msg ::= gen-success-msg SP 'REMOVED'
	                   ::= gen-noop-msg SP 'NOT IN LIST'
	listrm-failure-msg ::= gen-unknownobj-msg
	                   ::= gen-unknownlist-msg
	                   ::= gen-unknownobjref-msg
	
	* Creates a SET event in the transaction object.

4.8 Command: COMMIT	

	The COMMIT command has two phases - commit and status.  The commit
	phase takes all pending changes and creates a new transaction object
	out of them, and puts the transaction object in the queue for
	Event Dispatcher to process.  The status phase puts the connection in
	the status state (see section 4).  Once in the status state, status
	info messages will be delivered as they become available.  This is 
	equivalent to issuing the CHECK command for a transaction.  When the 
	transaction is complete, the connection will transition back to the 
	read state and return the commit completion status.  COMMIT
	inhibits any client from obtaining a lock, for the duration of the
	COMMIT, and when complete, will automatically release any locks held 
	by the calling transaction.

	commit-cmd ::= 'COMMIT' SP txid 
	commit-success-msg ::= gen-success-msg SP 'COMPLETED SUCCESSFULLY'
	                   ::= gen-noop-msg SP 'NOTHING TO COMMIT'
	commit-failure-msg ::= '4230' SP 'COMMIT QUEUE FULL' 
	                   ::= '4231' SP 'COMPLETED UNSUCCCESSFULLY' 
	                   ::= gen-locked-msg
	status-info-msg ::= '1230' SP 'COMMITTING' SP transacion-id NL 
	                ::= '1231' SP 'INFO' SP message-string 
	status-warn-msg ::= '3230' SP 'WARN' SP message-string 

	* Status info will be kept for 1 day from the time the COMMIT
	  completes, at which time it will be cleared by the next garbage
	  collection
	
4.9 Command: CANCEL	

	Cancel currently outstanding changes for the specified uncommited
	transaction, or aborts the running transaction (from the status
	state), or tries to abort the transaction specified in another
	session.  CANCEL will automatically release any locks held by the 
	transaction.

	cancel-cmd ::= 'CANCEL' [SP txid] 
	cancel-success-msg ::= gen-success-msg SP 'CANCELED'
	                   ::= gen-noop-msg SP 'NOTHING TO CANCEL'
	cancel-failure-msg ::= gen-unknowntxn-msg
	                   ::= '4241' SP 'TRANSACTION ALREADY COMPLETE' 
	
4.10 Command: LOCK
	
	The LOCK command attempts to put a lock on the object or objects 
	specified in the global object tree, to prevent other clients from 
	making modifications during a transaction.  The command will 
	repeatedly attemp to obtain the lock for 10 seconds, or 'numsecs' 
	seconds, if specified.  If the NOTIMEOUT clause is specified, the 
	lock will try indefinately.  This will effectively lock the 
	connection, and is not recommended.

	If a COMMIT is in progress, LOCK will behave as if the entire
	object tree is locked.

	lock-cmd ::= 'LOCK' SP oid [SP oid]* 
	             [SP ('TIMEOUT' SP numsecs | 'NOTIMEOUT')]
	lock-success-msg ::= gen-success-msg SP 'LOCKED'
	lock-failure-msg ::= gen-unknownobj-msg
	                 ::= gen-locked-msg

	* The only supported lock in version 1.0 is LOCK 0 - the root object,
	  which creates a global lock on the entire tree. The lock 
	  capabilities will get more granular with future revisions.

4.11 Command: UNLOCK

	The UNLOCK command is the complement of the LOCK command.  Clients
	who call LOCK should call a corresponding UNLOCK.  UNLOCK may only
	be called by the user who called LOCK, or by the super-user.  This
	command is not commonly needed, and is implied by CANCEL, COMMIT,
	and BYE.

	unlock-cmd ::= 'UNLOCK' SP (oid | 'ALL') 
	unlock-success-msg ::= gen-success-msg SP 'UNLOCKED'
	                   ::= gen-noop-msg SP 'NOT LOCKED'
	unlock-failure-msg ::= gen-unknownobj-msg


5 Status state

	When a COMMIT or CHECK command is issued, the connection enters the 
	status state, where the only commands accepted are:
	  BYE	    	terminate the session, but detatch the transaction
	  CANCEL    	cancel the transaction, if it has not completed
	  BG		disconnect the status session, return to read state

5.1 Command: BG

	BG puts the current COMMIT in the background.  This disconnects the
	client from the status state, and returns to read state, where the
	client may begin a new transaction.  The new transaction may also
	be COMMITed, but only one COMMIT is running on the backend at a
	time.  Other COMMITs will be put into a queue, and executed in
	turn.

	bg-cmd ::= 'BG' 
	bg-success-msg ::= gen-success-msg SP 'DISCONNECTED'


6 Actuator state

	The Event Dispatcher and the Event Handler (Actuator) use the CSCP
	protocol in the actuator state to communicate with each other.  The 
	actuator state is similar to the transaction state with the following 
	changes:
	
	Additional commands:
	  WHOAMI    	what user owns this transaction?
	  MYCHANGES 	list changes invoking this actuator
	  ALLCHANGES	list all changes in this transaction 
	  INFO	    	emit an info message
	  WARN	    	emit a warning
	  LOG		emit a logged message
	  EXIT	    	alert the event dispatcher that this actuator is
	  		done, and pass a return code (OK | FAIL | RESCHEDULE)

	Non-functional commands:
	  BEGIN
	  COMMIT
	  CANCEL
	  CHECK
	  LOCK
	  UNLOCK

	The last fundamental change from read state is that if data
	being changed by the transaction is queried, the value which will
	be written at the end of the transaction is returned, rather than
	the data which is currently stored.  This shadowing allows
	actuators to retrieve values as they will be.

	When the actuator is dispatched, it's open file descriptors are as
	follows:
	  0 (stdin):  read from event dispatcher
	  1 (stdout): write commands to event dispatcher
	  2 (stderr): write log entries to CCE log

	Actuator developers are encouraged to use the INFO, WARN, and LOG
	commands, to generate log messages, but the stderr mapping is 
	provided for extra convenience.
	
6.1 Command: WHOAMI

	Retrieve the authentication information for the currently
	authenticated user.

	whoami-cmd ::= 'WHOAMI' 
	whoami-success-msg ::= gen-success-msg SP username 

6.2 Command: MYCHANGES

	Return a list of changes that would have invoked this actuator.

	mychanges-cmd ::= 'MYCHANGES' 
	mychanges-success-msg ::= gen-success-msg SP change-list 
		
5.3 Command: ALLCHANGES

	Return a list of changes in the current transaction.

	allchanges-cmd ::= 'ALLCHANGES' 
	allchanges-success-msg ::= gen-success-msg SP change-list 
	
6.4 Command: INFO

	Emit an information level message to the commit message
	buffer and CCE log.

	info-cmd ::= 'INFO' SP message-text 
	info-success-msg ::= gen-success-msg SP 'LOGGED'
			
6.4 Command: WARN

	Emit a warning level message to the commit message buffer
	and CCE log.

	warn-cmd ::= 'WARN' SP message-text 
	warn-success-msg ::= gen-success-msg SP 'LOGGED'

6.5 Command: LOG

	Log a message to the CCE log, but do not put it into the
	commit message buffer.

	log-cmd ::= 'LOG' SP message 
	log-success-msg ::= gen-success-msg SP 'LOGGED'
		
6.6 Command: EXIT

	exit-cmd ::= 'EXIT' SP ('OK' | 'RESCHEDULE' | 'FAIL') 
	exit-success-msg ::= gen-success-msg SP 'THANK YOU' 
	                 ::= gen-success-msg SP 'RESCHEDULED' 
	                 ::= gen-success-msg SP 'TOO BAD' 


7 General messages

	These are all messages that may be issued in response to more than
	one command.  All general messages may have a command specific
	message payload attached.

	generic-msgs ::= gen-success-msgs | gen-fatal-msgs | gen-nonfatal-msgs
	
	Success messages:

	gen-success-msg ::= '2010'

	The gen-success-msg is the return code issued by all commands for a
	normal termination.
	
	gen-noop-msg ::= '2011'

	The gen-noop-msg is the return code issued when the configuration
	change requested is already true.


	Session-fatal messages:

	The server may issue any of these messages at any time they are thus
	all prefixed with 0.

	gen-fatal-msgs ::= gen-timeout-msg | gen-shutdown-msg | gen-onfire-msg
	
	gen-timeout-msg ::= '0001' SP 'SESSION TIMEOUT' 
	
	The gen-timeout-msg indicates that the connection has been
	quiescent for too long, and the server has given up hope that
	the client will ever talk to it.  The server then closes the
	connection down.  Uncommitted changes are lost.
	
	gen-shutdown-msg ::= '0002' SP 'SHUTTING DOWN' 
	
	The gen-shutdown-msg indicates that the server received a SIGINT or
	SIGHUP, is being shut down, and must now close the connection.  
	Uncommitted changes are canceled.

	gen-onfire-msg ::= '0999' SP 'ENGINE ON FIRE' 
	
	Something really bad happenned, the CCE is attempting to restart itself
	to correct the problem.  The current session will now be closed.
	Uncommitted changes are canceled.


	Non-fatal messages:

	These are always issued in response to a command.

	gen-nonfatal-msgs ::= gen-accessdenied-msg 
				| gen-badcmd-msg | gen-badparams-msg
			      | gen-nomem-msg | gen-unknownclass-msg 
			      | gen-badtxn-msg | gen-unknowntxn-msg 
			      | gen-unknownobj-msg | gen-badcriteria-msg 
			      | gen-unknownprop-msg | gen-badvalue-msg i
			      | gen-unknownlist-msg | gen-unknownobjref-msg 
			      | gen-badsig-msg | gen-locked-msg

	gen-accessdenied-msg ::= '4010' SP 'ACCESS DENIED' 
	
	This is the generic message that any command can return if the user
	does not have sufficient access privileges to perform the requested
	command.
	
	gen-badcmd-msg ::= '4011' SP 'BAD COMMAND' 
	
	Could not parse command.

	gen-badparams-msg ::= '4012' SP 'BAD PARAMETERS' 
	
	Invalid or wrong number of command parameters.

	gen-nomem-msg ::= '4013' SP 'OUT OF MEMORY' 

	This error can happen at any phase where the server detects that
	memory is not available.  The session is not terminated and the
	client may retry, but the server may respond again with
	gen-nomem-msg.  The BYE command will always succeed.

	These errors are self-explanatory, and may be used by any command,
	where appropriate.

	gen-unknownclass-msg ::= '4014' SP 'UNKNOWN CLASS' 
	gen-badtxn-msg ::= '4015' SP 'BAD TRANSACTION'
	gen-unknowntxn-msg ::= '4016' SP 'UNKNOWN TRANSACTION'
	gen-unknownobj-msg ::= '4017' SP 'UNKNOWN OBJECT'
	gen-badcriteria-msg ::= '4018' SP 'BAD CRITERIA' 
	gen-unknownprop-msg ::= '4019' SP 'UNKNOWN PROPERTY' 
	gen-badvalue-msg ::= '4020' SP 'BAD VALUE'
	gen-unknownlist-msg ::= '4021' SP 'UNKNOWN LIST' 
	gen-unknownobjref-msg ::= '4022' SP 'UNKNOWN OBJECT REFERENCE'
	gen-badsig-msg ::= '4023' SP 'BAD SIGNATURE'
	gen-locked-msg ::= '4024' SP 'LOCKED'

8 Command specific message-id allocation

	The first character indicates message type, middle characters 
	identify the issuing command, last character indicates unique 
	error code.

	    ?00?	AUTH
	    ?10?	CLIENTAUTH
	    ?11?	HELP
	    ?12?	NEW
	    ?13?	DESTROY
	    ?14?	FIND
	    ?15?	OIDOF
	    ?16?	SET
	    ?17?	GET
	    ?18?	TOUCH
	    ?18?	TYPE
	    ?19?	LISTADD
	    ?20?	LISTRM
	    ?21?	BEGIN
	    ?22?	LIST
	    ?23?	COMMIT
	    ?24?	CANCEL
	    ?25?	CHECK
	    ?26?	LOCK
	    ?27?	UNLOCK
	    ?28?	CLASSVER
	    ?29?	DEFINE
	    ?30?	UNDEFINE
	    ?31?	STRUCTURE
	    ?32?	EXTEND
	    ?33?	CLASSLIST
	    ?34?	WHOAMI
	    ?35?	MYCHANGES
	    ?36?	ALLCHANGES
	    ?37?	INFO
	    ?38?	WARN
	    ?39?	LOG
	    ?40?	EXIT
	    ?41?	CLASSACL
	    ?42?	REAUTH
	    ?43?	BG
	    ?44?	UNSET
	    ?45?	TYPEDEF
	    ?46?	TYPEUNDEF
	    ?47?	TYPELIST
	    ?99?	BYE

