ndb_redis: README file update. redis_cmd variadic function.
[sip-router] / modules / ndb_redis / README
1 NDB_REDIS Module
2
3 Daniel-Constantin Mierla
4
5    <miconda@gmail.com>
6
7 Edited by
8
9 Daniel-Constantin Mierla
10
11    <miconda@gmail.com>
12
13 Vicente Hernando
14
15    <vhernando@systemonenoc.com>
16
17    Copyright © 2011 asipto.com
18
19    Copyright © 2012 www.systemonenoc.com
20      __________________________________________________________________
21
22    Table of Contents
23
24    1. Admin Guide
25
26         1. Overview
27         2. Dependencies
28
29               2.1. Kamailio Modules
30               2.2. External Libraries or Applications
31
32         3. Parameters
33
34               3.1. server (str)
35
36         4. Functions
37
38               4.1. redis_cmd(srvname, command, ..., replyid)
39               4.2. redis_free(replyid)
40
41    List of Examples
42
43    1.1. Set server parameter
44    1.2. redis_cmd usage
45    1.3. redis_free usage
46
47 Chapter 1. Admin Guide
48
49    Table of Contents
50
51    1. Overview
52    2. Dependencies
53
54         2.1. Kamailio Modules
55         2.2. External Libraries or Applications
56
57    3. Parameters
58
59         3.1. server (str)
60
61    4. Functions
62
63         4.1. redis_cmd(srvname, command, ..., replyid)
64         4.2. redis_free(replyid)
65
66 1. Overview
67
68    This module provides a connector to interact with REDIS NoSQL Database
69    from configuration file. You can read more about REDIS at
70    http://redis.io.
71
72    It can connect to many REDIS servers and store the results in different
73    containers.
74
75 2. Dependencies
76
77    2.1. Kamailio Modules
78    2.2. External Libraries or Applications
79
80 2.1. Kamailio Modules
81
82    The following modules must be loaded before this module:
83      * none.
84
85 2.2. External Libraries or Applications
86
87    The following libraries or applications must be installed before
88    running Kamailio with this module loaded:
89      * hiredis - available at https://github.com/antirez/hiredis .
90
91 3. Parameters
92
93    3.1. server (str)
94
95 3.1. server (str)
96
97    Specify the details to connect to REDIS server. It takes a list of
98    attribute=value separated by semicolon, the attributes can be name,
99    unix, addr, port and db. Name is a generic identifier to be used with
100    module functions. unix is the path to the unix domain socket provided
101    by redis server. addr and port are the IP address and the port to
102    connect to REDIS server. unix and (addr, port) are mutually exclusive.
103    If both appear in same server settings unix domain socket is
104    configured. db is the DB number to use (defaults to 0 if not
105    specified).
106
107    You can set this parameter many times, in case you want to connect to
108    many REDIS servers, just give different attributes and use the specific
109    server name when querying the REDIS instance.
110
111    Default value is NULL.
112
113    Example 1.1. Set server parameter
114 ...
115 modparam("ndb_redis", "server", "name=srvN;addr=127.0.0.1;port=6379;db=1")
116 modparam("ndb_redis", "server", "name=srvX;addr=127.0.0.2;port=6379;db=4")
117
118 # Unix domain socket
119 modparam("ndb_redis", "server", "name=srvY;unix=/tmp/redis.sock;db=3")
120 ...
121
122 4. Functions
123
124    4.1. redis_cmd(srvname, command, ..., replyid)
125    4.2. redis_free(replyid)
126
127 4.1.  redis_cmd(srvname, command, ..., replyid)
128
129    Send a command to REDIS server identified by srvname. The reply will be
130    stored in a local container identified by replyid. All the parameters
131    can be strings with pseudo-variables that are evaluated at runtime.
132
133    Minimum required arguments are srvname, command and replyid. Command
134    argument can be separated into several ones using %s token. (See
135    examples) Total number of arguments cannot exceed six.
136
137    The reply can be accessed via pseudo-variable $redis(key). The key can
138    be: type - type of the reply (as in hiredis.h); value - the value
139    returned by REDIS server; info - in case of error from REDIS, it will
140    contain an info message.
141
142    If reply type is an array (as in hiredis.h), there are other keys
143    available:
144      * size - returns number of elements in the array.
145      * type[n] - returns the type of the nth element in the array. type -
146        returns array type.
147      * value[n] - returns value of the nth element. value - returns null
148        for an array. You need to get each element by index.
149
150    Example 1.2. redis_cmd usage
151 ...
152 if(redis_cmd("srvN", "INCR cnt", "r")) {
153     # success - the incremented value is in $redis(r=>value)
154     xlog("===== $redis(r=>type) * $redis(r=>value)\n");
155 }
156
157 # set a value
158 redis_cmd("srvN", "SET foo bar", "r");
159
160 redis_cmd("srvN", "SET ruri $ru", "r");
161
162 # get a value
163 redis_cmd("srvN", "GET foo", "r");
164
165 # same command separated into two arguments:
166 redis_cmd("srvN", "GET %s", "foo", "r");
167
168 # if we have a key with spaces within it:
169 redis_cmd("srvN", "GET %s", "foo bar", "r");
170
171 # several values substitution:
172 redis_cmd("srvN", "HMGET %s %s %s", "key1", "field1", "field2", "r");
173
174
175 # array example
176 if(redis_cmd("srvN", "HMGET foo_key field1 field3", "r")) {
177     xlog("array size: $redis(r=>size)\n");
178     xlog("first values: $redis(r=>value[0]) , $redis(r=>value[1])\n");
179 }
180 ...
181
182 4.2.  redis_free(replyid)
183
184    Frees data in a previous reply from memory. After this function call,
185    accessing to a freed replyid returns null value.
186
187    It is not necessary to free a reply to use it again in a new redis_cmd
188    function. When ndb_redis module closes, all pending replies are freed
189    automatically.
190
191    Example 1.3. redis_free usage
192 ...
193 After a redis command call:
194         redis_cmd("srvN", "INCR cnt", "r");
195
196 free reply data:
197         redis_free("r");
198 ...