modules: readme files regenerated - evapi ... [skip ci]
[sip-router] / src / modules / evapi / README
1 EVAPI 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    Copyright © 2014 asipto.com
14      __________________________________________________________________
15
16    Table of Contents
17
18    1. Admin Guide
19
20         1. Overview
21         2. Dependencies
22
23               2.1. Kamailio Modules
24               2.2. External Libraries or Applications
25
26         3. Parameters
27
28               3.1. workers (int)
29               3.2. bind_addr (str)
30               3.3. netstring_format (int)
31               3.4. event_callback (str)
32
33         4. Functions
34
35               4.1. evapi_relay(evdata)
36               4.2. evapi_async_relay(evdata)
37               4.3. evapi_multicast(evdata, etag)
38               4.4. evapi_async_multicast(evdata, etag)
39               4.5. evapi_unicast(evdata, etag)
40               4.6. evapi_async_unicast(evdata, etag)
41               4.7. evapi_close()
42               4.8. evapi_set_tag(tname)
43
44         5. Event routes
45
46               5.1. evapi:connection-new
47               5.2. evapi:connection-closed
48               5.3. evapi:message-received
49
50         6. Exported pseudo-variables
51
52    List of Examples
53
54    1.1. Set workers parameter
55    1.2. Set bind_addr parameter
56    1.3. Set netstring_format parameter
57    1.4. Set event_callback parameter
58    1.5. evapi_relay usage
59    1.6. TCP message
60    1.7. evapi_async_relay usage
61    1.8. evapi_multicast usage
62    1.9. evapi_async_multicast usage
63    1.10. evapi_unicast usage
64    1.11. evapi_async_unicast usage
65    1.12. evapi_close usage
66    1.13. evapi_set_tag usage
67
68 Chapter 1. Admin Guide
69
70    Table of Contents
71
72    1. Overview
73    2. Dependencies
74
75         2.1. Kamailio Modules
76         2.2. External Libraries or Applications
77
78    3. Parameters
79
80         3.1. workers (int)
81         3.2. bind_addr (str)
82         3.3. netstring_format (int)
83         3.4. event_callback (str)
84
85    4. Functions
86
87         4.1. evapi_relay(evdata)
88         4.2. evapi_async_relay(evdata)
89         4.3. evapi_multicast(evdata, etag)
90         4.4. evapi_async_multicast(evdata, etag)
91         4.5. evapi_unicast(evdata, etag)
92         4.6. evapi_async_unicast(evdata, etag)
93         4.7. evapi_close()
94         4.8. evapi_set_tag(tname)
95
96    5. Event routes
97
98         5.1. evapi:connection-new
99         5.2. evapi:connection-closed
100         5.3. evapi:message-received
101
102    6. Exported pseudo-variables
103
104 1. Overview
105
106    The EVAPI module can be used to create an event message flow from
107    Kamailio to any application that can connect to a TCP socket. The
108    remote application can also issue messages received by Kamailio.
109
110    There is no protocol definition, it is all up to the author of the
111    routing script. Events can be generated for any event in Kamailio. For
112    3rd party transaction control, a transaction can be automatically
113    suspended when sending the event, to be resumed at a later point, maybe
114    triggered by an incoming message on the event socket.
115
116 2. Dependencies
117
118    2.1. Kamailio Modules
119    2.2. External Libraries or Applications
120
121 2.1. Kamailio Modules
122
123    The following modules must be loaded before this module:
124      * tm - (optional) needed only by evapi_async_relay()
125
126 2.2. External Libraries or Applications
127
128    The following libraries or applications must be installed before
129    running Kamailio with this module loaded:
130      * libev - http://software.schmorp.de/pkg/libev
131
132 3. Parameters
133
134    3.1. workers (int)
135    3.2. bind_addr (str)
136    3.3. netstring_format (int)
137    3.4. event_callback (str)
138
139 3.1. workers (int)
140
141    Number of worker processes to be started to handle incoming messages
142    from remote applications.
143
144    Default value is 1.
145
146    Example 1.1. Set workers parameter
147 ...
148 modparam("evapi", "workers", 2)
149 ...
150
151 3.2. bind_addr (str)
152
153    Local IP and port to listen on for incoming TCP connections.
154
155    Default value is "127.0.0.1:8448".
156
157    Example 1.2. Set bind_addr parameter
158 ...
159 modparam("evapi", "bind_addr", "1.2.3.4:8228")
160 ...
161
162 3.3. netstring_format (int)
163
164    Control if messages on the socket (to and from clients) are
165    encapsulated in netstring format.
166
167    Default value is 1 (netstring format).
168
169    Example 1.3. Set netstring_format parameter
170 ...
171 modparam("evapi", "netstring_format", 0)
172 ...
173
174 3.4. event_callback (str)
175
176    The name of the function in the kemi configuration file (embedded
177    scripting language such as Lua, Python, ...) to be executed instead of
178    event_route[...] blocks.
179
180    The function receives a string parameter with the name of the event,
181    the values are: 'evapi:connection-new', 'evapi:connection-closed',
182    'evapi:message-received'.
183
184    Default value is 'empty' (no function is executed for events).
185
186    Example 1.4. Set event_callback parameter
187 ...
188 modparam("evapi", "event_callback", "ksr_evapi_event")
189 ...
190 -- event callback function implemented in Lua
191 function ksr_evapi_event(evname)
192         KSR.info("===== evapi module triggered event: " .. evname .. "\n");
193         return 1;
194 end
195 ...
196
197 4. Functions
198
199    4.1. evapi_relay(evdata)
200    4.2. evapi_async_relay(evdata)
201    4.3. evapi_multicast(evdata, etag)
202    4.4. evapi_async_multicast(evdata, etag)
203    4.5. evapi_unicast(evdata, etag)
204    4.6. evapi_async_unicast(evdata, etag)
205    4.7. evapi_close()
206    4.8. evapi_set_tag(tname)
207
208 4.1.  evapi_relay(evdata)
209
210    Relay the event data given as parameter to connected applications.
211
212    The format on the network is netstring with evdata payload if
213    netstring_format parameter is set to 1 or bare evdata if
214    netstring_format parameter is set to 0.
215
216    The function is passing the task to evapi dispatcher process, therefore
217    the SIP worker process is not blocked. Also, it doesn't wait for any
218    response, therefore the processing of the configuration continues very
219    fast when executing evapi_relay().
220
221    This function can be used from ANY_ROUTE.
222
223    Example 1.5. evapi_relay usage
224 ...
225 evapi_relay("{ \"event\": \"test\",\n \"data\": { \"fU\": \"$fU\" }\n}");
226 ...
227
228    The above exaple will send the following message over tcp:
229
230    Example 1.6. TCP message
231 ...
232 47:{
233  "event": "test",
234  "data": { "fU": "test" }
235 },
236 ...
237
238 4.2.  evapi_async_relay(evdata)
239
240    Relay the event data given as parameter to connected applications.
241    Before evaluating the parameter, the request processing is suspended
242    using tm module (using the t_suspend()/t_continue() framework). The
243    routing of the SIP request can be continued once
244    event_route[evapi:message-received] is triggered. After
245    evapi_async_relay() returns true, no relaying should happen in
246    request_route(), it should be followed by exit;.
247
248    The format on the network is netstring with evdata payload if
249    netstring_format parameter is set to 1 or bare evdata if
250    netstring_format parameter is set to 0.
251
252    This function can be used from REQUEST_ROUTE.
253
254    Example 1.7. evapi_async_relay usage
255 ...
256 evapi_async_relay("{ \"event\": \"suspend\",\n \"data\":"
257         " { \"index\": \"$T(id_index)\", \"label\": \"$T(id_label)\" }\n}");
258 ...
259
260 4.3.  evapi_multicast(evdata, etag)
261
262    Relay the event data given as parameter to connections that match the
263    tag provided by etag value. The etag can be a variable. For more see
264    evapi_relay() and evapi_set_tag().
265
266    Example 1.8. evapi_multicast usage
267 ...
268 evapi_multicast("{ \"event\": \"test\",\n \"data\": { \"fU\": \"$fU\" }\n}", "ta
269 gx");
270 ...
271
272 4.4.  evapi_async_multicast(evdata, etag)
273
274    Async relay the event data given as parameter to connections that match
275    the tag provided by etag value. The etag can be a variable. For more
276    see evapi_async_relay() and evapi_set_tag().
277
278    Example 1.9. evapi_async_multicast usage
279 ...
280 evapi_async_multicast("{ \"event\": \"suspend\",\n \"data\":"
281     " { \"index\": \"$T(id_index)\", \"label\": \"$T(id_label)\" }\n}", "tagx");
282 ...
283
284 4.5.  evapi_unicast(evdata, etag)
285
286    Relay the event data given as parameter to the first connection that
287    match the tag provided by etag value. The etag can be a variable. For
288    more see evapi_relay() and evapi_set_tag().
289
290    Example 1.10. evapi_unicast usage
291 ...
292 evapi_unicast("{ \"event\": \"test\",\n \"data\": { \"fU\": \"$fU\" }\n}", "tagx
293 ");
294 ...
295
296 4.6.  evapi_async_unicast(evdata, etag)
297
298    Async relay the event data given as parameter to the first connection
299    that match the tag provided by etag value. The etag can be a variable.
300    For more see evapi_async_relay() and evapi_set_tag().
301
302    Example 1.11. evapi_async_unicast usage
303 ...
304 evapi_async_unicast("{ \"event\": \"suspend\",\n \"data\":"
305     " { \"index\": \"$T(id_index)\", \"label\": \"$T(id_label)\" }\n}", "tagx");
306 ...
307
308 4.7.  evapi_close()
309
310    Close evapi current client connection.
311
312    This function can be used from ANY_ROUTE.
313
314    Example 1.12. evapi_close usage
315 ...
316 event_route[evapi:connection-new] {
317   if($evapi(srcaddr)!="127.0.0.1") {
318     evapi_close();
319     exit;
320   }
321 }
322 ...
323
324 4.8.  evapi_set_tag(tname)
325
326    Set tag name for current client connection. The parameters has to be a
327    string up to 64 characters. It can also be a variable holding such
328    string.
329
330    This function can be used from ANY_ROUTE.
331
332    Example 1.13. evapi_set_tag usage
333 ...
334 event_route[evapi:connection-new] {
335   if($evapi(srcaddr)=="127.0.0.1") {
336     evapi_set_tag("local");
337     exit;
338   }
339 }
340 ...
341
342 5. Event routes
343
344    5.1. evapi:connection-new
345    5.2. evapi:connection-closed
346    5.3. evapi:message-received
347
348 5.1.  evapi:connection-new
349
350    If defined, the module calls event_route[evapi:connection-new] when a
351    new client is connected.
352 ...
353 event_route[evapi:connection-new] {
354     xlog("new connection from $evapi(srcaddr):$evapi(srcport)\n");
355 }
356 ...
357
358 5.2.  evapi:connection-closed
359
360    If defined, the module calls event_route[evapi:connection-closed] when
361    a client connection is closed.
362 ...
363 event_route[evapi:connection-closed] {
364     xlog("connection closed by $evapi(srcaddr):$evapi(srcport)\n");
365 }
366 ...
367
368 5.3.  evapi:message-received
369
370    If defined, the module calls event_route[evapi:message-received] when a
371    message is received from a client.
372 ...
373 event_route[evapi:message-received] {
374     xlog("received [$evapi(msg)] from $evapi(srcaddr):$evapi(srcport)\n");
375 }
376 ...
377
378 6. Exported pseudo-variables
379
380      * $evapi(srcaddr) - source ip
381      * $evapi(srcport) - source port
382      * $evapi(msg) - received event message
383      * $evapi(conidx) - internal connection index
384
385    Exported pseudo-variables are documented at
386    http://www.kamailio.org/wiki/.