LIRC libraries: Client API

LIRC libraries Linux Infrared Remote Control

Loading...
Searching...
No Matches
Files | Classes | Functions
Client API

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

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

## Classes
struct | lirc_cmd_ctx
| The data needed to run a command on remote server. More...

## Functions
int | lirc_init (const char *prog, int verbose)
| Initial setup: connect to lircd socket. More...
void | lirc_set_verbose (int verbose)
| Dynamically change the verbose level defined by lirc_init(). More...
int | lirc_deinit (void)
| Release resources allocated by lirc_init(), basically disconnect from socket. More...
int | lirc_readconfig (const char *path, struct lirc_config **config, int(check)(char *s))
| Parse a lircrc configuration file. More...
void | lirc_freeconfig (struct lirc_config *config)
| Deallocate an object retrieved using lirc_readconfig(). More...
char * | lirc_nextir (void)
char * | lirc_ir2char (struct lirc_config *config, char *code)
int | lirc_nextcode (char **code)
| Get next available code from the lircd daemon. More...
int | lirc_code2char (struct lirc_config *config, char *code, char **string)
| Translate a code string to an application string using .lircrc. More...
int | lirc_readconfig_only (const char *file, struct lirc_config **config, int(check)(char *s))
| Parse a lircrc configuration file without connecting to lircrcd. More...
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)
| Retrieve default lircrcd socket path. More...
const char * | lirc_getmode (struct lirc_config *config)
| Get mode defined in lircrc. More...
const char * | lirc_setmode (struct lirc_config *config, const char *mode)
| Set mode defined in lircrc. More...
int | lirc_command_init (lirc_cmd_ctx *ctx, const char *fmt,...)
| Initiate a lirc_cmd_ctx to run a command. More...
int | lirc_command_run (lirc_cmd_ctx *ctx, int fd)
| Run a command in non-blocking mode. More...
void | lirc_command_reply_to_stdout (lirc_cmd_ctx *ctx)
| Set command_ctx write_to_stdout flag. More...
int | lirc_send_one (int fd, const char *remote, const char *keysym)
| Send keysym using given remote. More...
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. More...
int | lirc_get_remote_socket (const char *address, int port, int quiet)
| Return an opened and connected file descriptor to remote lirc socket. More...
int | lirc_get_local_socket (const char *path, int quiet)
| Return an opened and connected file descriptor to local lirc socket. More...

## 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.cpp

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.cpp.

## Function Documentation

## ◆ lirc_code2char()

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 1813 of file lirc_client.c.

## ◆ lirc_code2charprog()

int lirc_code2charprog | ( | struct lirc_config * | config,
|  | char * | code,
|  | char ** | string,
|  | char ** | prog
| ) |  |

Definition at line 1843 of file lirc_client.c.

## ◆ lirc_command_init()

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 110 of file lirc_client.c.

## ◆ lirc_command_reply_to_stdout()

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 127 of file lirc_client.c.

## ◆ lirc_command_run()

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 190 of file lirc_client.c.

## ◆ lirc_deinit()

int lirc_deinit | ( | void |  | ) |

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

Definition at line 365 of file lirc_client.c.

## ◆ lirc_freeconfig()

void lirc_freeconfig | ( | struct lirc_config * | config | ) |

Deallocate an object retrieved using lirc_readconfig().

Definition at line 1534 of file lirc_client.c.

## ◆ lirc_get_local_socket()

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 2056 of file lirc_client.c.

## ◆ lirc_get_remote_socket()

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 2078 of file lirc_client.c.

## ◆ lirc_getmode()

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 1946 of file lirc_client.c.

## ◆ lirc_getsocketname()

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 1937 of file lirc_client.c.

## ◆ lirc_init()

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 344 of file lirc_client.c.

## ◆ lirc_ir2char()

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

Deprecated:
  obsolete

Definition at line 1726 of file lirc_client.c.

## ◆ lirc_nextcode()

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 1879 of file lirc_client.c.

## ◆ lirc_nextir()

char * lirc_nextir | ( | void |  | ) |

Deprecated:
  obsolete

Definition at line 1861 of file lirc_client.c.

## ◆ lirc_readconfig()

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 1447 of file lirc_client.c.

## ◆ lirc_readconfig_only()

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 1526 of file lirc_client.c.

## ◆ lirc_send_one()

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 1995 of file lirc_client.c.

## ◆ lirc_set_verbose()

void lirc_set_verbose | ( | int | verbose | ) |

Dynamically change the verbose level defined by lirc_init().

Definition at line 384 of file lirc_client.c.

## ◆ lirc_setmode()

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 1967 of file lirc_client.c.

## ◆ lirc_simulate()

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 the 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 2010 of file lirc_client.c.