kamailio/modules/ndb_redis/README

NDB_REDIS Module

Daniel-Constantin Mierla

   <miconda@gmail.com>

Edited by

Daniel-Constantin Mierla

   <miconda@gmail.com>

Vicente Hernando

   <vhernando@systemonenoc.com>

   Copyright © 2011 asipto.com

   Copyright © 2012 www.systemonenoc.com
     __________________________________________________________________

   Table of Contents

   1. Admin Guide

        1. Overview
        2. Dependencies

              2.1. Kamailio Modules
              2.2. External Libraries or Applications

        3. Parameters

              3.1. server (str)

        4. Functions

              4.1. redis_cmd(srvname, command, ..., replyid)
              4.2. redis_free(replyid)

   List of Examples

   1.1. Set server parameter
   1.2. redis_cmd usage
   1.3. redis_free usage

Chapter 1. Admin Guide

   Table of Contents

   1. Overview
   2. Dependencies

        2.1. Kamailio Modules
        2.2. External Libraries or Applications

   3. Parameters

        3.1. server (str)

   4. Functions

        4.1. redis_cmd(srvname, command, ..., replyid)
        4.2. redis_free(replyid)

1. Overview

   This module provides a connector to interact with REDIS NoSQL Database
   from configuration file. You can read more about REDIS at
   http://redis.io.

   It can connect to many REDIS servers and store the results in different
   containers.

2. Dependencies

   2.1. Kamailio Modules
   2.2. External Libraries or Applications

2.1. Kamailio Modules

   The following modules must be loaded before this module:
     * none.

2.2. External Libraries or Applications

   The following libraries or applications must be installed before
   running Kamailio with this module loaded:
     * hiredis - available at https://github.com/antirez/hiredis .

3. Parameters

   3.1. server (str)

3.1. server (str)

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

   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.

   Default value is NULL.

   Example 1.1. Set server parameter
...
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")
...

4. Functions

   4.1. redis_cmd(srvname, command, ..., replyid)
   4.2. redis_free(replyid)

4.1.  redis_cmd(srvname, command, ..., replyid)

   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.

   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.

   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.

   If reply type is an array (as in hiredis.h), there are other keys
   available:
     * size - returns number of elements in the array.
     * type[n] - returns the type of the nth element in the array. type -
       returns array type.
     * value[n] - returns value of the nth element. value - returns null
       for an array. You need to get each element by index.

   Example 1.2. redis_cmd usage
...
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");
}
...

4.2.  redis_free(replyid)

   Frees data in a previous reply from memory. After this function call,
   accessing to a freed replyid returns null value.

   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.

   Example 1.3. redis_free usage
...
After a redis command call:
        redis_cmd("srvN", "INCR cnt", "r");

free reply data:
        redis_free("r");
...