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