1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
|
<?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>
|
