123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209 |
- <?xml version="1.0" encoding='ISO-8859-1'?>
- <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
- "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd" [
- <!-- Include general documentation entities -->
- <!ENTITY % docentities SYSTEM "../../../docbook/entities.xml">
- %docentities;
- ]>
- <!-- Module User's Guide -->
- <chapter>
-
- <title>&adminguide;</title>
-
- <section>
- <title>Overview</title>
- <para>
- This module provides a connector to interact with REDIS NoSQL Database
- from configuration file. You can read more about REDIS at
- http://redis.io.
- </para>
- <para>
- It can connect to many REDIS servers and store the results in different
- containers.
- </para>
- </section>
- <section>
- <title>Dependencies</title>
- <section>
- <title>&kamailio; Modules</title>
- <para>
- The following modules must be loaded before this module:
- <itemizedlist>
- <listitem>
- <para>
- <emphasis>none</emphasis>.
- </para>
- </listitem>
- </itemizedlist>
- </para>
- </section>
- <section>
- <title>External Libraries or Applications</title>
- <para>
- The following libraries or applications must be installed before running
- &kamailio; with this module loaded:
- <itemizedlist>
- <listitem>
- <para>
- <emphasis>hiredis</emphasis> - available at
- https://github.com/antirez/hiredis .
- </para>
- </listitem>
- </itemizedlist>
- </para>
- </section>
- </section>
- <section>
- <title>Parameters</title>
- <section id="ndb_redis.p.server">
- <title><varname>server</varname> (str)</title>
- <para>
- Specify the details to connect to REDIS server. It takes a list of
- attribute=value separated by semicolon, the attributes can be
- name, unix, addr, port and db. Name is a generic identifier to be used
- with module functions. unix is the path to the unix domain socket provided
- by redis server. addr and port are the IP address and the port to
- connect to REDIS server. unix and (addr, port) are mutually exclusive.
- If both appear in same server settings unix domain socket is configured.
- db is the DB number to use (defaults to 0 if not specified).
- </para>
- <para>
- You can set this parameter many times, in case you want to connect to
- many REDIS servers, just give different attributes and use the specific
- server name when querying the REDIS instance.
- </para>
- <para>
- <emphasis>
- Default value is NULL.
- </emphasis>
- </para>
- <example>
- <title>Set <varname>server</varname> parameter</title>
- <programlisting format="linespecific">
- ...
- modparam("ndb_redis", "server", "name=srvN;addr=127.0.0.1;port=6379;db=1")
- modparam("ndb_redis", "server", "name=srvX;addr=127.0.0.2;port=6379;db=4")
- # Unix domain socket
- modparam("ndb_redis", "server", "name=srvY;unix=/tmp/redis.sock;db=3")
- ...
- </programlisting>
- </example>
- </section>
- </section>
- <section>
- <title>Functions</title>
- <section id="ndb_redis.f.redis_cmd">
- <title>
- <function moreinfo="none">redis_cmd(srvname, command, ..., replyid)</function>
- </title>
- <para>
- Send a command to REDIS server identified by srvname. The reply will
- be stored in a local container identified by replyid. All the
- parameters can be strings with pseudo-variables that are evaluated
- at runtime.
- </para>
- <para>
- Minimum required arguments are srvname, command and replyid. Command argument
- can be separated into several ones using %s token. (See examples)
- Total number of arguments cannot exceed six.
- </para>
- <para>
- The reply can be accessed via pseudo-variable $redis(key). The key
- can be: type - type of the reply (as in hiredis.h); value - the value
- returned by REDIS server; info - in case of error from REDIS, it will
- contain an info message.
- </para>
- <para>
- If reply type is an array (as in hiredis.h), there are other keys
- available:
- <itemizedlist>
- <listitem>
- <para>
- size - returns number of elements in the array.
- </para>
- </listitem>
- <listitem>
- <para>
- type[n] - returns the type of the nth element in the array. type
- - returns array type.
- </para>
- </listitem>
- <listitem>
- <para>
- value[n] - returns value of the nth element. value - returns null
- for an array. You need to get each element by index.
- </para>
- </listitem>
- </itemizedlist>
- </para>
- <example>
- <title><function>redis_cmd</function> usage</title>
- <programlisting format="linespecific">
- ...
- if(redis_cmd("srvN", "INCR cnt", "r")) {
- # success - the incremented value is in $redis(r=>value)
- xlog("===== $redis(r=>type) * $redis(r=>value)\n");
- }
- # set a value
- redis_cmd("srvN", "SET foo bar", "r");
- redis_cmd("srvN", "SET ruri $ru", "r");
- # get a value
- redis_cmd("srvN", "GET foo", "r");
- # same command separated into two arguments:
- redis_cmd("srvN", "GET %s", "foo", "r");
- # if we have a key with spaces within it:
- redis_cmd("srvN", "GET %s", "foo bar", "r");
- # several values substitution:
- redis_cmd("srvN", "HMGET %s %s %s", "key1", "field1", "field2", "r");
- # array example
- if(redis_cmd("srvN", "HMGET foo_key field1 field3", "r")) {
- xlog("array size: $redis(r=>size)\n");
- xlog("first values: $redis(r=>value[0]) , $redis(r=>value[1])\n");
- }
- ...
- </programlisting>
- </example>
- </section>
- <section id="ndb_redis.f.redis_free">
- <title>
- <function moreinfo="none">redis_free(replyid)</function>
- </title>
- <para>
- Frees data in a previous reply from memory.
- After this function call, accessing to a freed replyid returns null value.
- </para>
- <para>
- It is not necessary to free a reply to use it again in a new redis_cmd
- function. When ndb_redis module closes, all pending replies are freed
- automatically.
- </para>
- <example>
- <title><function>redis_free</function> usage</title>
- <programlisting format="linespecific">
- ...
- After a redis command call:
- redis_cmd("srvN", "INCR cnt", "r");
- free reply data:
- redis_free("r");
- ...
- </programlisting>
- </example>
- </section>
- </section>
- </chapter>
|