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 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!