Desc: Commands sent to the UPS modules
File: new-modules.txt
Date: 20 November 1999

By using the SysV message passing scheme, upsd can send commands to the
individual support programs and receive their responses.  To support this
in a module, the following things must happen...

1. Call createmsgq().  This will take care of all the interesting system
   functions that actually make the message queue.  Then it adds the 
   queue ID to your info[] array with addinfo.  So, make sure you have at
   least one unused entry in there or this will fail silently.

2. Add "extern struct ups_handler upsh;" to the global section of your
   program.  You'll use this later to add pointers to functions. 

3. Install handlers for everything you plan to support.  At this writing,
   there is only one command - for setting variables in the UPS.  If your
   module's function for handling this is called my_ups_set(), then
   you'd do this to add the pointer:

   upsh.setvar = my_ups_set;

   my_ups_set() will receive three parameters:

   int auxcmd - the type being set, see shared.h for the values
   int dlen   - data length
   char *data - pointer to the actual value that should be set

4. In your idle loop, call getupsmsg regularly.  This will check for
   messages and parse them according to your function pointers.

Responses
---------

Model programs may be expected to send responses to commands.  There is a
function provided for lightweight reply-only message sending.  Use it when
upsd expects some sort of message back from you.

For success: msgreply(UPSMSG_REPOK) - reply, status OK

For failure: msgreply(UPSMSG_ERRCF) - error, command failed

See include/shared.h for more error/reply possibilities.

Other info
----------

This document assumes you are making use of upscommon to handle
compatibility.  If you strike out on your own and implement this yourself
(brave...) then the function calls don't apply.
