Protocol version 0
~~~~~~~~~~~~~~~~~~

Cmd   Client-->Server       Server-->Client
---   -------------------   ----------------------
  0   Connection            Connection/sensor list
  1   Listen request        Listen response
  2                         Sensor value update
  3   Shm request           Shm response

Status codes
-------------------------------
  0 = OK
  1 = Bad packet
  2 = Not accepting connections
  3 = Sensor duplicated
  4 = Sensor out of range
  5 = No shm available

client: argus_connect(), argus_async_connect()

    Client opens UNIX domain socket.
    Client writes protocol version code to server.
        (byte) packet length
        (byte) command (0)
        (byte) client version
    Server responds with its version code and with the sensor list.
        (byte) packet length
        (byte) command (0)
        (byte) status
        if status == 0:
            (byte) server version
            (byte) total sensor count
            (byte) number of sensors in this packet
            (byte) sensor #0: name length
            (str)  sensor #0: name characters (no terminating \0)
            (byte) sensor #1: name length
            (str)  sensor #1: name characters (no terminating \0)
            ...
    If the sensor names would cause the packet length field to overflow,
    multiple packets are sent.
    Client and server use the least-common-denominator protocol version.

client: argus_disconnect(), [shutdown]

    Client closes UNIX domain socket fd.
    Server removes client from connected list.

server: [shutdown]

    Server closes UNIX domain socket fd.
    Client crashes. :^)

client: argus_listen(), argus_async_listen()

    Client sends list of sensors.
        (byte) packet length
        (byte) command (1)
        (byte) sensor count
        (byte) index of requested sensor #0
        (byte) index of requested sensor #1
        ...
    Server sends confirmation.
        (byte) packet length
        (byte) command (1)
        (byte) status
        if status == 3 or status == 4:
            (byte) index of error
    If there were no errors, server hereafter continually sends value updates
    on the named sensors.  It immediately sends the current values and then
    sends further packets only when at least one of the named sensors changes,
    up until the client disconnects or changes its listen list.
     
server: [value change on sensor]

    Server sends new values for all sensors client is listening to.
        (byte) packet length
        (byte) command (2)
        (byte) status
        if status == 0:
            (byte) requested sensor #0: value
            (byte) requested sensor #1: value
            ...

client: argus_open_shm(), argus_async_open_shm()

    Client sends shm request.
        (byte) packet length
        (byte) command (3)
    Server sends shm key.
        (byte) packet length
        (byte) command (3)
        (byte) status
        if status == 0:
            (key_t) shm key
    Client and server both break socket connection.

client: argus_close_shm()

    Client closes shm with shmdt().  This doesn't involve the socket.

# vim: set ts=4 sts=4 sw=4 tw=80 et syn=off: