Desc: Commands sent to the UPS modules
File: commands.txt
Date: 3 February 2000
Auth: Russell Kroll <rkroll@exploits.org>

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 are only two commands:

   - setvar  = setting UPS variables (SET protocol command)
   - instcmd = instant UPS commands (INSTCMD protocol command)

   If your module's function for handling variable set events 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   - the type being set, see shared.h for the values
   int   - data length
   *char - pointer to the actual value that should be set

   Do something similar for instcmd if you support it.  Don't set a value
   for functions that aren't implemented.

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.

This functionality is not currently used or expected by upsd.

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.
