\hypertarget{group__client__manual}{}\section{Client A\+P\+I manual excerpt.}
\label{group__client__manual}\index{Client A\+P\+I manual excerpt.@{Client A\+P\+I manual excerpt.}}


lirc\+\_\+client Client A\+P\+I manual excerpt \label{_lirc_client}%
  


lirc\+\_\+client Client A\+P\+I manual excerpt \label{_lirc_client}%
 



 \begin{center}\subsection*{The lirc\+\_\+client A\+P\+I}\end{center} 

\begin{center}\end{center}  

 

Since 0.\+6.\+0, the client A\+P\+I have supported receiving data. Since 0.\+9.\+2+, the A\+P\+I also supports sending of data. 

This text is also available in the \href{api-docs}{\tt A\+P\+I documentation} (under Modules). This variant is more detailed, and linked by Doxygen to the sources. 

\paragraph*{Receiving data}

If you only want to make your application to receive commands and if you don\textquotesingle{}t want to mess with all the protocol stuff you can use the {\itshape lirc\+\_\+client} library that comes with L\+I\+R\+C since version 0.\+6.\+0. With the help of this library a program can be as simple as this to receive data. 


\begin{DoxyPre}\end{DoxyPre}



\begin{DoxyPre}    /****************************************************************************
        irexec.c ****************************************************************\end{DoxyPre}



\begin{DoxyPre}       irexec  - execute programs according to the pressed remote control buttons\end{DoxyPre}



\begin{DoxyPre}       Copyright (C) 1998 Trent Piepho <\href{mailto:xyzzy@u.washington.edu}{\tt xyzzy@u.washington.edu}>
       Copyright (C) 1998 Christoph Bartelmus <\href{mailto:lirc@bartelmus.de}{\tt lirc@bartelmus.de}>\end{DoxyPre}



\begin{DoxyPre}     */\end{DoxyPre}



\begin{DoxyPre}    #ifdef HAVE\_CONFIG\_H
    \# include <config.h>
    #endif\end{DoxyPre}



\begin{DoxyPre}    #include <errno.h>
    #include <unistd.h>
    #include <stdarg.h>
    #include <stdio.h>
    #include <stdlib.h>
    #include <string.h>
    #include "lirc\_client.h"\end{DoxyPre}



\begin{DoxyPre}    char *progname;\end{DoxyPre}



\begin{DoxyPre}    int main(int argc, char *argv[])
    \{
            struct \hyperlink{structlirc__config}{lirc\_config} *config;
            char *code;
            char *c;
            int ret;\end{DoxyPre}



\begin{DoxyPre}            progname=argv[0];
            if(argc>2)
            \{
                    fprintf(stderr,"Usage: %s &lt;config file&gt;\(\backslash\)n",progname);
                    exit(EXIT\_FAILURE);
            \}
            if( lirc\_init("irexec",1) == -1)
                    exit EXIT\_FAILURE;\end{DoxyPre}



\begin{DoxyPre}            if( lirc\_readconfig(argc == 2 ? argv[1] : NULL,\&config,NULL) == 0) \{
                    while( lirc\_nextcode(\&code) == 0)
                    \{
                            if (code == NULL) continue;
                            while(( ret = lirc\_code2char( config,code,\&c)) == 0 \&\&
                                  c != NULL)
                            \{
                                   printf("Execing command \(\backslash\)"\%s"\textbackslash{}n",c);
                                   system(c);
                            \}
                            free(code);
                            if(ret==-1) break;
                    \}
                    lirc\_freeconfig(config);
            \}\end{DoxyPre}



\begin{DoxyPre}            \hyperlink{group__lirc__client_ga50999022b09857ba43aa2f3f29c72b9e}{lirc\_deinit()};
            exit(EXIT\_SUCCESS);
    \}
\end{DoxyPre}


Before anything else you have to include the header file for the lirc\+\_\+client library. This is done with 


\begin{DoxyPre}
    #include <lirc/lirc\_client.h>
\end{DoxyPre}
 

Note that our example differs in this point because it was taken directly from the lirc-\/0.\+6.\+0 source that comes with its own {\itshape \hyperlink{lirc__client_8h}{lirc\+\_\+client.\+h}} but we have to use the one that is already installed on the system. 

The next step is to initialize the library code with {\itshape \hyperlink{group__lirc__client_gaf92c865f0895259aa40e2aed51c71001}{lirc\+\_\+init()}}. This function connects to lircd and does some internal init stuff. 


\begin{DoxyPre}
    int lirc\_init(char *prog,int verbose);
\end{DoxyPre}
 

The first argument to this function is the string users will have to provide as {\itshape prog} token in their .lircrc config files. If the second argument is non-\/zero error messages will be printed to {\itshape stderr}. Otherwise no error messages will ever be displayed. This function returns the file descriptor of the socket that is connected to lircd or -\/1 if an error occurred. 

By default the client connects to the hard-\/coded default path, usually /var/run/lirc/lircd. The environment variable L\+I\+R\+C\+\_\+\+S\+O\+C\+K\+E\+T\+\_\+\+P\+A\+T\+H can be used to connect to another socket. 

The example continues by reading a config file. This is done by the {\itshape \hyperlink{group__lirc__client_ga62e50c43a39bd8858d42bc11adf40972}{lirc\+\_\+readconfig()}} function\+: 


\begin{DoxyPre}
    int lirc\_readconfig(char *file,struct \hyperlink{structlirc__config}{lirc\_config} **config,
                        int (check)(char *s));
\end{DoxyPre}
 

If you want to load the default config file you should pass N\+U\+L\+L as first argument. If you want to load some other config file the {\itshape file} argument should contain the complete path to the file. Your program should give the user the possibility to use an other than the default config file. You should also be able to load multiple config files by calling this function several times.~\newline


The {\itshape config} argument is used to pass the pointer to the config file data structures back to your application. You will need it for calls to the {\itshape \hyperlink{group__lirc__client_ga8cb15780179dec56adc42559ee964a68}{lirc\+\_\+code2char()}} function. The last argument is a call-\/back function that can be used to do syntax checks with the config strings. The library code will call the call-\/back function for all config strings where the {\itshape prog} token in the config file matches the prog string you provided with the {\itshape \hyperlink{group__lirc__client_gaf92c865f0895259aa40e2aed51c71001}{lirc\+\_\+init()}} function. If there is an error in the config string the call-\/back function should return -\/1, otherwise 0. If you don\textquotesingle{}t need to do any syntax checks you can pass N\+U\+L\+L here. The function returns -\/1 if an error occurred, 0 otherwise. 

The {\itshape \hyperlink{group__lirc__client_gaf352dc9bb17d32c0f867ce5ca8a2f2d3}{lirc\+\_\+nextcode()}} function blocks until there is something available on the lircd socket. This way it can be used in the main loop of your program like in our example. 


\begin{DoxyPre}
    int \hyperlink{group__lirc__client_gaf352dc9bb17d32c0f867ce5ca8a2f2d3}{lirc\_nextcode(char **code)};
\end{DoxyPre}
 

If an error occurs (usually this means that the socket has been closed by the daemon) this function returns -\/1. Otherwise it returns 0 and {\itshape code} points to the next string available in the data stream. This string has to be freed by your application using the {\itshape free(3)} function. If no complete string is available {\itshape code} will be N\+U\+L\+L.~\newline


If you use some G\+U\+I-\/toolkit for your program then you probably won\textquotesingle{}t be able to use this function in your program\textquotesingle{}s main loop because this is already handled by the G\+U\+I-\/toolkit. In this situation you should use the call-\/back abilities of the toolkit that will notify you whenever there is some input available from a file descriptor (you get the file descriptor from the {\itshape \hyperlink{group__lirc__client_gaf92c865f0895259aa40e2aed51c71001}{lirc\+\_\+init()}} function). E.\+g. you can use the {\itshape gdk\+\_\+input\+\_\+add()}/{\itshape gdk\+\_\+input\+\_\+remove}() functions with gtk or the {\itshape Q\+Socket\+Notifier} class with Qt. If you don\textquotesingle{}t have such functionality in your toolkit or can\textquotesingle{}t use it for some reason you can still use S\+I\+G\+I\+O signals for this purpose. Check the documentation for your G\+U\+I-\/toolkit and signal(2) for further information.~\newline


Please note that using call-\/backs you still have to use some kind of while loop to read strings from the socket because several strings may be available in the data stream and you will only get a notification for the first one. This poses a problem for us because {\itshape \hyperlink{group__lirc__client_gaf352dc9bb17d32c0f867ce5ca8a2f2d3}{lirc\+\_\+nextcode()}} blocks until there is something available from the socket which is not what we need here. You can solve this problem by setting the {\bfseries O\+\_\+\+N\+O\+N\+B\+L\+O\+C\+K} flag for the socket using the {\itshape fcntl(2)} function. Have a look at the current xirw code that is available from the L\+I\+R\+C homepage for an implementation example. 

To get the config string that the user has provided in the config file in response to a button press you use the following function\+: 


\begin{DoxyPre}
    int \hyperlink{group__lirc__client_ga8cb15780179dec56adc42559ee964a68}{lirc\_code2char(struct lirc\_config *config,char *code,char **string)};
\end{DoxyPre}
 

{\itshape config} is a pointer to the config file data structure that you can get with {\itshape \hyperlink{group__lirc__client_ga62e50c43a39bd8858d42bc11adf40972}{lirc\+\_\+readconfig()}} and {\itshape code} is the code transmitted to your application on the lircd socket. If an action should be taken {\itshape string} will point to the config string the user has provided in the config file. The user might want to take several actions on a button press so you have to execute this function until {\itshape string} is N\+U\+L\+L, which means that no more actions shall be taken, or an error occurs. The function returns -\/1 if an error occurred, 0 otherwise. 

In our example there are only two clean-\/up functions to be explained. 


\begin{DoxyPre}
    void \hyperlink{group__lirc__client_ga771f0592a8d378bc2ea314fdf4efa233}{lirc\_freeconfig(struct lirc\_config *config)};
\end{DoxyPre}
 

This functions frees the data structures associated with {\itshape config}. 


\begin{DoxyPre}
    int \hyperlink{group__lirc__client_ga50999022b09857ba43aa2f3f29c72b9e}{lirc\_deinit()};
\end{DoxyPre}
 

{\itshape \hyperlink{group__lirc__client_ga50999022b09857ba43aa2f3f29c72b9e}{lirc\+\_\+deinit()}} closes the connection to lircd and does some internal clean-\/up stuff. 

\paragraph*{Sending data}

Sending (blasting) is done according to following\+:


\begin{DoxyPre}\end{DoxyPre}



\begin{DoxyPre}#include "lirc\_client.h"\end{DoxyPre}



\begin{DoxyPre}int main(int argc, char** argv)
\{
    int fd;\end{DoxyPre}



\begin{DoxyPre}    fd = lirc\_get\_local\_socket(NULL, 0);
    if (fd < 0) \{
        // Process error
    \}
    if (lirc\_send\_one(fd, "name of remote", "Key symbol") == -1) \{
        // Process errors
    \};
\}
\end{DoxyPre}


Notes\+: 
\begin{DoxyItemize}
\item Feeding N\+U\+L\+L to \hyperlink{group__lirc__client_ga13cf4c784df60143d2b171645f4e84c1}{lirc\+\_\+get\+\_\+local\+\_\+socket()} will make it use the default lircd socket. Doing so, it respects the L\+I\+R\+C\+\_\+\+S\+O\+C\+K\+E\+T\+\_\+\+P\+A\+T\+H environment variable. 
\item {\itshape Name of remote} is the mandatory name attribute in the lircd.\+conf config file. 
\item {\itshape Key symbol} is the name of a key definition in the lircd.\+conf file. 
\end{DoxyItemize}\hyperlink{group__lirc__client_ga0e86e3a29c14dc8047651e0bb9c49b31}{lirc\+\_\+send\+\_\+one()} and \hyperlink{group__lirc__client_gad5d41d33e0c1fc3002cdf8c0d9aa43d5}{lirc\+\_\+simulate()} are blocking. If you need to do non-\/blocking I\+O and/or access other functionality available you need to use \hyperlink{group__lirc__client_ga3787c58d32391a5b7c40337fdbee95fc}{lirc\+\_\+command\+\_\+init()} and \hyperlink{group__lirc__client_ga888d275e1b0cf4988e44fb15f24d2a99}{lirc\+\_\+command\+\_\+run()}. Example code is in irsend.\+cpp.

\paragraph*{Autoconf support}

I encourage you to use autoconf and automake for your projects. To check for the lirc\+\_\+client library all you have to insert into your {\itshape configure.\+ac} (or {\itshape configure.\+in}) file is the following\+: 


\begin{DoxyPre}
    dnl Check for LIRC client support
    PKG\_CHECK\_MODULES([LIRC], [lirc],,)
\end{DoxyPre}
 

This will setup the variables L\+I\+R\+C\+\_\+\+F\+L\+A\+G\+S and L\+I\+R\+C\+\_\+\+L\+I\+B\+S which can be used to augment A\+M\+\_\+\+C\+P\+P\+F\+L\+A\+G\+S and A\+M\+\_\+\+L\+I\+B\+S. See pkg-\/config(3). 