git.sip-router.org Git - sip-router/blob - 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/.