lirccd 0.9 README
-----------------
LIRC client daemon written by Fredrik Tolf (fredrik@dolda2000.cjb.net)

IMPORTANT notice for those upgrading from lirccd 0.8
----------------------------------------------------
The client interaction module has been completely revised in lirccd
0.9. liblircc has been obsoleted - please remove it from your hard
drive completely, programs that use it will not function with lirccd
anymore. Instead, a new liblirc_client has been written that contains
new calls for lirccd and still retains binary compatibility with the
liblirc_client that comes with the LIRC distribution. This
liblirc_client automatically starts up lirccd if it isn't already
running. If it does so, lirccd is given the -c argument, which makes
it terminate itself when the last client disconnects. Also, the client
program protocol has been completely revised. Do _not_ rely on the old
behavior anymore; it will not work. In the standard way of not
documenting anymore than necessary about lirccd, I won't write anymore
about it here. If you want more info, either look at the source or
send a mail and bug me to write documentation.

On the configuration file side, not much has changed, but that which
has is quite important. The only change is that the configuration file
should now be named ~/.lircrc instead of ~/.lirccrc.

Some more primitive functions have been added that you can use,
though. See usercommands.c for info (or, again, send me a mail and bug
me to write docs).

Software Requirements
---------------------
- lircd, see http://www.lirc.org/
- If you have what lircd requires, you should be fine

Options
-------
- The -C option allows the user the specify the location of the
  configuration file. The default is $HOME/.lirccrc
- The -s option allows the user the specify the location of the socket
  file created by lirccd. Be careful, though: if the file name is
  already occupied, it will be unlinked automatically. The default is
  $HOME/.lircc

Getting lirccd
--------------
The current official location is
http://www.dolda2000.cjb.net/~fredrik/lirccd/
Someday I will probably get a sourceforge page for it.

I also heavily recommend downloading the Festival text-to-speech
system. One possible source for this is to go to http://rpmfind.net/
and search for the festival RPM. Even if you don't have the RPM system
or don't want an RPM, that will diplay the URL to the project which
hopefully is more up-to-date than I can have here.

Building lirccd
---------------
The usual, ./configure and make.

Installing lirccd
-----------------
make install should do the trick.

Disclaimer
----------

This software is licensed under the Gnu General Public License (the GPL). If
you do not have a local copy of this (it should be distributed with this
source, see the file COPYING), download it from
http://www.fsf.org/licenses/gpl.txt
The author(s) are, of course, not to be held responsible for any possible
damage this software may in any way do to your system.

Configuration
-------------
The default config file name is $HOME/.lirccrc (see also the -C option
above). The configuration file format allows for very versatile
configuration using a C-like script language. See the file
lirccrc.example that came with the source distribution for how to use
this language. It should be rather descriptive. No other docs are
currently available. For a complete list of functions that can be used
in the configuration file, see the function regusercommands at the end
of src/usercommands.c

Client program interface
------------------------
The UNIX socket created by lirccd allows client programs to connect
and recieve commands sent by the configuration script using the
sendstring() built in function. The sendstring() function takes two
string arguments: the name of the target application and the string to
be sent. In the standard documentation tradition of lirccd, the exact
details of the protocol will not be documented here. See the source or
send me a mail and bug me for documentation (or even better, write it
for me) if you want to know the protocol. However, that should not
even be necessary. Just use the functions described here instead.

Starting with lirccd 0.9, a replacement for the standard
liblirc_client shipped with LIRC is included. If lirccd is not
running, it starts it (with the -c flag, which makes lirccd terminate
when the last client disconnects from the socket), and then uses the
client protocol to communicate.

The program should include the file lirc_client.h, which is installed
in /usr/local/include/lirc by default. #include <lirc/lirc_client.h>
should work.

The client program then begins by calling the lirc_init2 function. The
function has the following syntax:

int lirc_init2(char *APPNAME, int VERBOSE, char *SOCKET, ...);

The APPNAME parameter specifies the application name to be sent to
lirccd, and SOCKET specifies the socket file to connect to. SOCKET can
also be specified as NULL, which implies the default socket file name
($HOME/.lircc). Set VERBOSE to zero if you want liblirc_client to shut
up even if it encounters an error (which will otherwise be printer on
stderr). The ellipses is reserved for future use. For now, set it to
NULL to be compatible with future versions. lirc_init2 returns the
file descriptor of the socket connected to lirccd if the call
succeeds, and a negative value if the call fails, in which case errno
is set to the error encountered.

The old lirc_init call is also available, although deprecated. It's a
simple wrapper function to lirc_init2, with fewer arguments:

int lirc_init(char *APPNAME, int VERBOSE);

It behaves exactly as lirc_init2 with SOCKET and the ellipses set to
NULL.

After initializing, the client program can call lirc_getmesg() to
receive commands sent by lirccd. lirc_getmesg has the following
syntax:

int lirc_getmesg(char **BUF, int BLOCK);

If there is a command waiting, lirc_getmesg will return zero, setting
*BUF to a buffer allocated with malloc containing the received
message. You _must_ free this memory manually. To have lircc_getmesg
block until a message is avaiable, pass BLOCK as 1, other wise 0. If
non-blocking behavior is selected and no message is available,
lirc_getmesg will return a negative value and errno set to EAGAIN. If
an error occurs, it will return a negative value and errno set
appropriately.

If the client program still wants to allow the library to shut down
cleanly, it should call lircc_deinit, which takes no parameters and
returns if the file descriptor was successfully closed, i.e. it has
the following syntax:

int lirc_deinit(void);

For more advanced stuff, there are more advanced functions at your
command. Starting with lirccd 0.9, you can send arbitrary commands to
lirccd. Not many are implemented at the moment, but to call one, use
the lirc_runcmd, which has the following syntax:

int lirc_runcmd(char ***WORDS, char *CMD, ...)

Set CMD to the command you want to run, and pass the arguments using
the ellipses, terminated with a NULL. If you provide a pointer to a
char ** variable in WORDS, lirc_runcmd will return all words that the
command returned. This must be freed using lirc_freewords (void
function taking the char ** as its argument). If you're not interested
in the exact words, pass NULL. The return value of lirc_runcmd will be
the numerical code returned by the command. In general, codes that
satisfy ((code / 100) == 1) are successful returns,
((code / 100) == 2) are successful, waiting for another command in a
command chain, ((code / 100) == 3) are syntax errors (invalid command,
wrong number of args, etc.), and ((code / 100) == 4) indicates a
command-specific failure, like "cap" telling you that input already is
captured.

Currently, these commands are avaiable:

ver - Return the protocol version as (retcode % 100).
ident - Identify your program (done by lirc_init2 unless you pass a
        NULL APPNAME).
raw - Tell lirccd to send you raw keypresses. These can be obtained
      using the lirc_getbutton function, described below. Pass "1" as
      the first argument to enable this functionality, and "0" to
      disable it.
cap - Capture the input. No events will be sent to other clients, and
      lirccd itself will not process keypresses any further. You can
      only receive raw keypresses while having captured input. Like
      above, these can be received with lirc_getbutton. Pass "1" as
      the first argument to capture the input, and "0" to release it
      again.

As mentioned, lirc_getbutton can be used to receive raw keypress
events. It has the following syntax:

int lirc_getbutton(char **CODE, int *REPEAT, char **BUTTON,
                   char **REMOTE, int BLOCK)

The return value and the BLOCK argument behaves as for lirc_getmesg -
see above for the details. The CODE, BUTTON and REMOTE should be a
pointer to a char *, which will be set to a buffer allocated with
malloc. You must free this manually. REPEAT should be a pointer to an
int. You can set any of CODE, REPEAT, BUTTON and REMOTE to NULL if
you're not interested in what it is.

There are some more functions, but if you're interested in them,
either see the source or send me a mail and bug me to write
documentation (or even better, write it for me). Good luck!
