UNOFFICIAL CODE.  DO NOT USE.

The code in libargus.c is by no means complete.  Most of it is actually quite
stale, having been written for a previous version of the API.  As such, it
cannot be used.

libargus.h, on the other hand, I am quite happy with.  But without some C files
for implementation, it too is useless.

In a very real sense, it's not a library at all, since no program can use it.

For this reason I think that there is no reason to rename it.  Think of it
instead as a collection of ideas about how an Argus library can be written.

In the future I'll implement it, and at such time I will rename it if it is
still considered to be non-standard.  But for the moment I don't want to spend
any time coding on it.  It's not at all important, since all the programs that
want to talk to Argus already do so using a working system (shm segments with
known keys).

The main reason I'm leaving libargus and argusd in the same archive as
Smartshelf is because they conceptually depend on evlist and prjlibs, which
aren't distributed separately.  If I ever do develop libargus/argusd, I'll
definitely move them to their own source tree, plus I may split off evlist and
the modified prjlibs.

Now, a word about compatibility.

Programs currently access Argus data using shared memory segments with known
structures and known keys.  If memory serves, the structure consists of an
array of unsigned char's.  The first eight represent eight analog values, and
the next two represent ten digital values.  In order for such a program to
connect to the Argus server, (1) there must be a shm with the expected key,
(2) it must fit the expected structure, and (3) there needs to be a program
filling it with useful data fresh from the Argus AD.

The argusd program I propose provides data to clients using three methods:

- Data is passed to the client through a connected UNIX domain socket.  This
  facilitates synchronous operation, the ability to request a limited set of
  sensors, and the convenience and flexibility of referring to sensors by name
  rather than by index.

- Data is passed to the client using a shm.  The shm structure consists of an
  array of int's, each of which can be used for an analog sensor whose values
  range from 0 to 255 or a digital sensor with values 0 or 1.  The names of
  each of the sensors in the array would have already been passed through the
  socket, along with the length of the array and the key required for attaching
  to the shm.

- Data is passed to the client using a shm.  The shm structure is a char array,
  as described above.  The client is expected to unpack bits for digital
  sensors, to know which indices contain the appropriate sensor data, and to
  know what key to use for attaching to the shm.

Therefore, argusd as I plan it should be fully backward compatible with all
existing programs, since the third method above is (should be?) equivalent to
the system currently in use.

Why use my libargus/argusd?

- If the protocol between client and server changes, all it takes to update the
  client is to restart its executable.  ld.so should dynamically link it to the
  new version of libargus.so which will know the new protocol.  Furthermore,
  the protocol is versioned, so even if libargus and argusd are mismatched they
  will still be able to negotiate a common protocol.

- Since sensors are referred to by name rather than by index, clients needn't
  worry about the specific order in which the sensors are wired into the Argus
  AD.  Also this allows for Argus devices with different sensor counts and for
  connecting multiple Argus AD's to a single server program.

- It should be completely backward compatible with existing programs.

- Client programs don't need to know the shm key_t in advance.

- Programs can operate synchronously (using the socket protocol), receiving
  immediate notification of all updates to the sensors they requested.  Or they
  can request a shm to get access to an automatically-updated array containing
  data for all sensors.

- All socket, protocol, and shm details are neatly wrapped in a clean API.

- It includes a nifty event loop routine which supports being extended to allow
  for a single program to connect to multiple argusd servers, monitor files,
  and schedule timed events all in the same loop without resorting to the use
  of threads, thereby avoiding synchronization headaches.

- It can be extended to use TCP or UDP to connect to remote servers without
  significantly affecting client programs.

Why not use my libargus/argusd?

- It's not finished.

- It could be less stable than the existing code, which by all appearances
  works just fine.

- My codebase is a fair amount larger than the currently-used codebase.

- It's not absolutely necessary.

- The current design does not support the full range of Argus devices, just the
  Argus AD in the kitchen.

- It might have problems with adding variable sampling rates in the future.

- It may add a tiny bit of overhead.

- Its shm system has no locking mechanism.

- I'm not always available to help fix problems with it.
