---------------------------------------
kissdx command protocol - Specification
---------------------------------------



OVERVIEW

There is a need to command kissdx to peform certain actions, e.g. 
to shut down, or to change the running configuration on the fly.



INITIAL THOUGHTS AND NOTES

kissdx already has a local command socket that is being used by child
processes to communicate on-the-fly configuration changes back to
the main kissdx process.

This local command socket will be used for communicating commands to
kissdx.

For kissdx to be controlled by other hosts on the network, the local
command socket will have to be replaced by a public TCP port.  This
feature is not covered by the initial specification.



USE CASES


USE CASE 1:  Child process communicates configuration change to main process.

This is the only use case that is already implemented as of kissdx 
0.13-10.  We will expand on this implementation to support the other
use cases.


USE CASE 2:  Another program sends a command to kissdx.

The external program must communicate a command to the running kissdx
(if there is one running).  This can be implemented like this:
a) scan /tmp/ for a file starting with kissdx-loccmdskt-
b) use the found filename to create a local client socket
c) send the command to that socket
d) receive response from kissdx if expected according to the protocol
e) handle the case where kissdx is not running / not receiving / not 
   responding


USE CASE 3:  A user shuts down kissdx in a controlled fasion.

This use case implements USE CASE 2, with a second instance of kissdx
as the external program.

The planned implementation is that the user starts a second instance
of kissdx with a special parameter that is the command to be executed,
e.g.

kissdx stop

On startup, the second instance of kissdx must check for a command
parameter (stop) and if found, it must act according to USE CASE 2
and then terminate normally (not daemoning, etc.).



PROTOCOL

The protocol uses upper-case ASCII characters.

Commands are NOT terminated by end-of-line character in the current
implementation, but they should be now that the protocol is being
expanded!  A single LF (decimal value 10, char value '\n') will be 
used to signal the end of a command.

These are the supported commands:

1.	SET LIST_HIDDEN_ENTRIES {ON|OFF}
	On receipt of this command, kissdx turns the display of hidden
	content on or off and resets the countdown timer for time-limited
	display of hidden contents if configured.
	Response:  none

2.	STOP
	On receipt of this command, kissdx exits immediately.
	Running child processes should be terminated.  Does this happen
	automatically?  MUST BE TESTED!
	The local command socket will be closed by kissdx, so the caller
	should close the socket immediately after sending the command.
	Response:  none

3.  More coming?



REFACTORING

kissdx 0.13-10 implements the protocol in connection.c (client side)
and kissdx.c (server side).  The command handling must be moved
into separate source files to isolate the implementation of the
command protocol:

cmdclient.c / cmdclient.h will implement the client side of the
communications.  Move code from connection.c:
	function deliver_local_command()

cmdserver.c / cmdserver.h will implement the server side of the
communications.  Move code from kissdx.c:
	function handle_local_command()
	function setup_local_commandserver_socket() 
	all variables used only by the functions above
	
Then expand on that for the new feature(s).
Start by adding '\n' to the command in the current implementation
(append \n on the client in function deliver_local_command(), scan
for \n on the server in handle_local_command()).


STATUS

Not implemented as of 2007-02-20.
Implementation is planned to be done by Olivier Kahn <okahn@free.fr>.