Desc: Commands sent to the UPS modules
File: new-modules.txt
Date: 24 August 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 shutdowns after some delay.  If your
   module's function for initiating this is called my_ups_shutdown(), then
   you'd do this to add the pointer:

   upsh.shutdown = my_ups_shutdown;

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

Responses
---------

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

One example is for shutdowns.  Certain models can acknowledge the command
in two ways - one says "OK, I'm going to do it" and the other says "I
can't shutdown now".  The model needs to convey this back to upsd.  All
you do is call msgreply() with the right argument.

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.
