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

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. The application specifies its name the first thing it does
when connecting to the socket by sending it verbatim followed by the
newline character ('\n').
The lircc client library (liblircc) is also available, which makes it
extremely easy for client programs to use the lircc interface.
The program should include the file lircc.h, which is installed in
/usr/local/include/lirc by default. #include <lirc/lircc.h> should
work.
The client program then begins by calling the lircc_init function. The
function has the following syntax:

int lircc_init(unsigned char *APPNAME, unsigned 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). lircc_init returns the file descriptor of the socket
connected to lirccd if the call succeeds, and a negative value if the
call fails.
After initializing, the client program can call lircc_getstr() to
receive commands sent by lirccd. lircc_getstr has the following
syntax:

unsigned char *lircc_getstr(int BLOCK);

If there is a command waiting, lircc_getstr will return a pointer to a
statically allocated buffer containing the command. If, for any
reason, the call fails, lircc_getstr will return NULL. If BLOCK is
non-zero, the lircc_getstr call will block until it receives a command
from lirccd, if none was waiting. If BLOCK is zero and there is no
command waiting, lircc_getstr will return NULL.
For more advanced programs, there is also lircc_getstr_r, which is
reentrant. It has the following syntax:

int lircc_getstr_r(unsigned char *BUF, int BUFLEN, int BLOCK);

The return buffer and its maximum length will be specified by the
caller using the BUF and BUFLEN parameters. BLOCK behaves like in
lircc_getstr. If the call succeeds, the number of bytes in the command
string is returned, or zero if BLOCK was zero and no command was
waiting. If BUFLEN is smaller than the number of characters in the
command, -1 will be returned, and the command will be discarded. If an
error occurred, -2 will be returned.
The only system resource held by the library is the file descriptor of
the socket. If the client program still wants to allow the library to
shut down cleanly, it should call lircc_cleanup, which takes no
parameters and returns no value, i.e. it has the following syntax:

void lircc_cleanup(void);

That should be all. Good luck!
