Client API

Basic interface to 3-rd party applications. More...

Files
file	lirc_client.h
	3-rd party application interface.

Data Structures
struct	lirc_cmd_ctx

Functions
int	lirc_init (const char *prog, int verbose)
int	lirc_deinit (void)
int	lirc_readconfig (const char *path, struct lirc_config **config, int(check)(char *s))
void	lirc_freeconfig (struct lirc_config *config)
char *	lirc_nextir (void)
char *	lirc_ir2char (struct lirc_config *config, char *code)
int	lirc_nextcode (char **code)
int	lirc_code2char (struct lirc_config *config, char *code, char **string)
int	lirc_readconfig_only (const char *file, struct lirc_config **config, int(check)(char *s))
int	lirc_code2charprog (struct lirc_config *config, char *code, char **string, char **prog)
size_t	lirc_getsocketname (const char *id, char *buf, size_t size)
const char *	lirc_getmode (struct lirc_config *config)
const char *	lirc_setmode (struct lirc_config *config, const char *mode)
int	lirc_command_init (lirc_cmd_ctx *ctx, const char *fmt,...)
int	lirc_command_run (lirc_cmd_ctx *ctx, int fd)
void	lirc_command_reply_to_stdout (lirc_cmd_ctx *ctx)
int	lirc_send_one (int fd, const char *remote, const char *keysym)
int	lirc_simulate (int fd, const char *remote, const char *keysym, int scancode, int repeat)
int	lirc_get_remote_socket (const char *address, int port, int quiet)
int	lirc_get_local_socket (const char *path, int quiet)

Detailed Description

Basic interface to 3-rd party applications.

The lirc_client interface is the basic interface for 3-rd party applications using lirc. It provides functions to retrieve , send and control button events to/from remotes.

Receiving events from remotes could be done according to the following example, a stripped down version of the irexec(1) tool.

   #include "lirc_client.h"

   int main(int argc, char* argv[])
   {
       const char* lircrc_path;
       struct lirc_config* config;
       char* code;
       char* s;

       // Check arguments... use argv[1] as lircrc config file path.
       lircrc_path = argc == 2 ? argv[1] : NULL;

       if (lirc_init("mythtv", 1) == -1) {
           // Process error and exit
       }
       if (lirc_readconfig(lircrc_path, &config, NULL) != 0) {
           // Process error and exit.
       }
       while (lirc_nextcode(&code) == 0) {
           if (code == NULL) continue;
           while (lirc_code2char(config, code, &s) == 0 && s != NULL) {
               // Do something with string s.
           }
           free(code);
       }
       lirc_freeconfig(config);
       lirc_deinit();
       exit(0);
   }

Some notes:

• lirc_init() connects to the lircd daemon socket. The program given as argument is used when we later call lirc_readconfig() to determine what translation(s) to use. Thus it should match the program = ... items in the lircrc config file.
• lirc_readconfig() parses the lircrc config file into &config. Using NULL as path means that the default lircrc file is used.
• lirc_nextcode() reads the next button event from lircd. For the purposes here the returned code is just an opaque handle. It will sometimes return on a timeout without any data available, thus the if (code == NULL) continue statement.
• lirc_code2char() translates the code handle to one ore more application specific string as defined in the licrrc file. Since more than one string can be returned lirc_code2char() should be called until it returns a NULL string.
• The complete source for this example is in irexec.c

Sending (blasting) is done according to following:

#include "lirc_client.h"

int main(int argc, char** argv)
{
    int fd;

    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
    };
}

Notes:

• Feeding NULL to lirc_get_local_socket() will make it use the default lircd socket. Doing so, it respects the LIRC_SOCKET_PATH environment variable.
• "Name of remote" is the mandatory name attribute in the lircd.conf config file.
• "Key symbol" is the name of a key definition in the lircd.conf file.
• lirc_send_one() and lirc_simulate() are blocking. If you need to do non-blocking IO and/or access other functionality available you need to use lirc_command_init() and lirc_command_run(). Example code is in irsend.c.

Function Documentation

int lirc_code2char	(	struct lirc_config *	config,
		char *	code,
		char **	string
	)

Translate a code string to an application string using .lircrc. An translation might return more than one string so this function should be called several times until *string == NULL.

Parameters

config	Parsed lircrc data from e. g. lirc_readconfig().
code	Code string e. g., as from lirc_nextcode().
string	On successfull exit points to a static application string, NULL if no more translations are available.

Returns

-1 on errors, else 0.

Definition at line 1792 of file lirc_client.c.

int lirc_command_init	(	lirc_cmd_ctx *	ctx,
		const char *	fmt,
			...
	)

Initiate a lirc_cmd_ctx to run a command.

Parameters

ctx	Undefined om input, ready to execute on exit.
fmt,...	printf-style formatting for command. Don't forget trailing "\n"!

Returns

0 on OK, else a kernel error code.

Note

Simple example: lirc_command_init(&ctx, "CODE %s\\n", code);

Since

0.9.2

Definition at line 104 of file lirc_client.c.

void lirc_command_reply_to_stdout

(

lirc_cmd_ctx *

ctx

)

Set command_ctx write_to_stdout flag. When set, the reply payload is written to stdout instead of the default behavior to store it in ctx->reply.

Since

0.9.2

Definition at line 121 of file lirc_client.c.

int lirc_command_run	(	lirc_cmd_ctx *	ctx,
		int	fd
	)

Run a command in non-blocking mode.

Parameters

ctx	Initiated data on enter, possibly reply payload in ctx->reply on exit.
fd	Open file connected to a lircd output socket.

Returns

0 on OK, else a kernel error code (possibly EAGAIN).

Since

0.9.2

Definition at line 179 of file lirc_client.c.

int lirc_deinit

(

void

)

Release resources allocated by lirc_init(), basically disconnect from socket.

Definition at line 353 of file lirc_client.c.

void lirc_freeconfig

(

struct lirc_config *

config

)

Deallocate an object retrieved using lirc_readconfig().

Definition at line 1513 of file lirc_client.c.

int lirc_get_local_socket	(	const char *	path,
		int	quiet
	)

Return an opened and connected file descriptor to local lirc socket.

Parameters

path	Path to socket. If NULL use LIRC_SOCKET_PATH in environment, falling back to a hardcoded lircd default.
quiet	If true, don't write error messages on stderr.

Returns

positive file descriptor on success, else a negated kernel error code.

Since

0.9.2

Definition at line 2028 of file lirc_client.c.

int lirc_get_remote_socket	(	const char *	address,
		int	port,
		int	quiet
	)

Return an opened and connected file descriptor to remote lirc socket.

Parameters

address	Remote host to connect to.
port	TCP port. If <= 0 uses hardcoded default LIRC_INET_PORT.
quiet	If true, don't write error messages on stderr.

Returns

positive file descriptor on success, else a negated kernel error code.

Since

0.9.2

Definition at line 2050 of file lirc_client.c.

const char* lirc_getmode

(

struct lirc_config *

config

)

Get mode defined in lircrc. Will use lircrcd if available, else local data.

Parameters

config

Parsed lircrc file as obtained from lirc_readconfig() or lirc_readconfig_only().

Returns

Current mode or NULL on errors.

Definition at line 1918 of file lirc_client.c.

size_t lirc_getsocketname	(	const char *	id,
		char *	buf,
		size_t	size
	)

Retrieve default lircrcd socket path.

Parameters

id	Optional socket id, defaults (id == NULL) to "default".
buf	Return buffer.
size	Size of return buffer.

Returns

-1 on errors, else 0.

Definition at line 1909 of file lirc_client.c.

int lirc_init	(	const char *	prog,
		int	verbose
	)

Initial setup: connect to lircd socket.

Parameters

prog	Name of client in logging contexts.
verbose	Amount of debug info on stdout.

Returns

positive file descriptor or -1 + error in global errno.

Definition at line 332 of file lirc_client.c.

char* lirc_ir2char	(	struct lirc_config *	config,
		char *	code
	)

Deprecated:

obsolete

Definition at line 1705 of file lirc_client.c.

int lirc_nextcode

(

char **

code

)

Get next available code from the lircd daemon.

Parameters

code	Undefined on enter. On exit either NULL if no complete code was available, else a pointer to a malloc()'d code string. Caller should eventually free() this.

Returns

-1 on errors, else 0 indicating either a complete code in *code or that nothing was available.

Definition at line 1851 of file lirc_client.c.

char* lirc_nextir

(

void

)

Deprecated:

obsolete

Definition at line 1833 of file lirc_client.c.

int lirc_readconfig	(	const char *	path,
		struct lirc_config **	config,
		int(check)(char *s)
	)

Parse a lircrc configuration file. This function will also try to connect to a lircrcd instance on the default socket which is derived from path.

Parameters

path	Path to lircrc config file. If NULL the default file is used.
config	Undefined omn enter, on successfull exit a pointer to an allocated lirc_config instance.
check	Callback function called with each configured application string as argument. Returns 0 if string is OK, else -1.

Returns

-1 on errors, else 0.

Definition at line 1426 of file lirc_client.c.

int lirc_readconfig_only	(	const char *	file,
		struct lirc_config **	config,
		int(check)(char *s)
	)

Parse a lircrc configuration file without connecting to lircrcd.

Parameters

path	Path to lircrc config file. If NULL the default file is used.
config	Undefined omn enter, on successfull exit a pointer to an allocated lirc_config instance.
check	Callback function called with each configured application string as argument. Returns o if string is OK, else -1.

Returns

-1 on errors, else 0.

Definition at line 1505 of file lirc_client.c.

int lirc_send_one	(	int	fd,
		const char *	remote,
		const char *	keysym
	)

Send keysym using given remote. This call might block for some time since it involves communication with lircd.

Parameters

fd	File descriptor for lircd socket. This must not be the descriptor returned by lirc_init(); open the socket using lirc_get_local_socket() or lirc_get_remote_socket()k instead.
remote	Name of remote, the 'name' attribute in the config file.
keysym	The code to send, as defined in the config file.

Returns

-1 on errors, else 0.

Since

0.9.2

Definition at line 1967 of file lirc_client.c.

const char* lirc_setmode	(	struct lirc_config *	config,
		const char *	mode
	)

Set mode defined in lircrc. Will use lircrcd if available, else use local data.

Parameters

config	Parsed lircrc file as obtained from lirc_readconfig() or lirc_readconfig_only().
mode	A new mode defined in lircrc.

Returns

New mode, should match mode unless there is errors.

Definition at line 1939 of file lirc_client.c.

int lirc_simulate	(	int	fd,
		const char *	remote,
		const char *	keysym,
		int	scancode,
		int	repeat
	)

Send a simulated lirc event.This call might block for some time since it involves communication with lircd.

Parameters

fd	File descriptor for lircd socket. This must not be the descriptor returned by lirc_init; open the socket using lirc_get_local_socket() or lirc_get_remote_socket() instead.
remote	Name of remote, the 'name' attribute in the config file.
keysym	The code to send, as defined in the config file.
scancode	The code bound the keysym in teh config file.
repeat	Number indicating how many times this code has been repeated, starts at 0, increased for each repetition.

Returns

-1 on errors, else 0.

Since

0.9.2

Definition at line 1982 of file lirc_client.c.