mirror of https://github.com/sipwise/kamailio.git
You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
274 lines
6.5 KiB
274 lines
6.5 KiB
EVAPI Module
|
|
|
|
Daniel-Constantin Mierla
|
|
|
|
<miconda@gmail.com>
|
|
|
|
Edited by
|
|
|
|
Daniel-Constantin Mierla
|
|
|
|
<miconda@gmail.com>
|
|
|
|
Copyright © 2014 asipto.com
|
|
__________________________________________________________________
|
|
|
|
Table of Contents
|
|
|
|
1. Admin Guide
|
|
|
|
1. Overview
|
|
2. Dependencies
|
|
|
|
2.1. Kamailio Modules
|
|
2.2. External Libraries or Applications
|
|
|
|
3. Parameters
|
|
|
|
3.1. workers (int)
|
|
3.2. bind_addr (str)
|
|
3.3. netstring_format (int)
|
|
|
|
4. Functions
|
|
|
|
4.1. evapi_relay(evdata)
|
|
4.2. evapi_async_relay(evdata)
|
|
4.3. evapi_close()
|
|
|
|
5. Event routes
|
|
|
|
5.1. evapi:connection-new
|
|
5.2. evapi:connection-closed
|
|
5.3. evapi:message-received
|
|
|
|
6. Exported pseudo-variables
|
|
|
|
List of Examples
|
|
|
|
1.1. Set workers parameter
|
|
1.2. Set bind_addr parameter
|
|
1.3. Set netstring_format parameter
|
|
1.4. evapi_relay usage
|
|
1.5. TCP message
|
|
1.6. evapi_async_relay usage
|
|
1.7. evapi_evapi usage
|
|
|
|
Chapter 1. Admin Guide
|
|
|
|
Table of Contents
|
|
|
|
1. Overview
|
|
2. Dependencies
|
|
|
|
2.1. Kamailio Modules
|
|
2.2. External Libraries or Applications
|
|
|
|
3. Parameters
|
|
|
|
3.1. workers (int)
|
|
3.2. bind_addr (str)
|
|
3.3. netstring_format (int)
|
|
|
|
4. Functions
|
|
|
|
4.1. evapi_relay(evdata)
|
|
4.2. evapi_async_relay(evdata)
|
|
4.3. evapi_close()
|
|
|
|
5. Event routes
|
|
|
|
5.1. evapi:connection-new
|
|
5.2. evapi:connection-closed
|
|
5.3. evapi:message-received
|
|
|
|
6. Exported pseudo-variables
|
|
|
|
1. Overview
|
|
|
|
The EVAPI module can be used to create an event message flow from
|
|
Kamailio to any application that can connect to a TCP socket. The
|
|
remote application can also issue messages received by Kamailio.
|
|
|
|
There is no protocol definition, it is all up to the author of the
|
|
routing script. Events can be generated for any event in Kamailio. For
|
|
3rd party transaction control, a transaction can be automatically
|
|
suspended when sending the event, to be resumed at a later point, maybe
|
|
triggered by an incoming message on the event socket.
|
|
|
|
2. Dependencies
|
|
|
|
2.1. Kamailio Modules
|
|
2.2. External Libraries or Applications
|
|
|
|
2.1. Kamailio Modules
|
|
|
|
The following modules must be loaded before this module:
|
|
* tm - (optional) needed only by evapi_async_relay()
|
|
|
|
2.2. External Libraries or Applications
|
|
|
|
The following libraries or applications must be installed before
|
|
running Kamailio with this module loaded:
|
|
* libev - http://software.schmorp.de/pkg/libev.html
|
|
|
|
3. Parameters
|
|
|
|
3.1. workers (int)
|
|
3.2. bind_addr (str)
|
|
3.3. netstring_format (int)
|
|
|
|
3.1. workers (int)
|
|
|
|
Number of worker processes to be started to handle incoming messages
|
|
from remote applications.
|
|
|
|
Default value is 1.
|
|
|
|
Example 1.1. Set workers parameter
|
|
...
|
|
modparam("evapi", "workers", 2)
|
|
...
|
|
|
|
3.2. bind_addr (str)
|
|
|
|
Local IP and port to listen on for incoming TCP connections.
|
|
|
|
Default value is "127.0.0.1:8448".
|
|
|
|
Example 1.2. Set bind_addr parameter
|
|
...
|
|
modparam("evapi", "bind_addr", "1.2.3.4:8228")
|
|
...
|
|
|
|
3.3. netstring_format (int)
|
|
|
|
Control if messages on the socket (to and from clients) are
|
|
encapsulated in netstring format.
|
|
|
|
Default value is 1 (netstring format).
|
|
|
|
Example 1.3. Set netstring_format parameter
|
|
...
|
|
modparam("evapi", "netstring_format", 0)
|
|
...
|
|
|
|
4. Functions
|
|
|
|
4.1. evapi_relay(evdata)
|
|
4.2. evapi_async_relay(evdata)
|
|
4.3. evapi_close()
|
|
|
|
4.1. evapi_relay(evdata)
|
|
|
|
Relay the event data given as parameter to connected applications.
|
|
|
|
The format on the network is netstring with evdata payload if
|
|
netstring_format parameter is set to 1 or bare evdata if
|
|
netstring_format parameter is set to 0.
|
|
|
|
The function is passing the task to evapi dispatcher process, therefore
|
|
the SIP worker process is not blocked. Also, it doesn't wait for any
|
|
response, therefore the processing of the configuration continues very
|
|
fast when executing evapi_relay().
|
|
|
|
This function can be used from ANY_ROUTE.
|
|
|
|
Example 1.4. evapi_relay usage
|
|
...
|
|
evapi_relay("{ \"event\": \"test\",\n \"data\": { \"fU\": \"$fU\" }\n}");
|
|
...
|
|
|
|
The above exaple will send the following message over tcp:
|
|
|
|
Example 1.5. TCP message
|
|
...
|
|
47:{
|
|
"event": "test",
|
|
"data": { "fU": "test" }
|
|
},
|
|
...
|
|
|
|
4.2. evapi_async_relay(evdata)
|
|
|
|
Relay the event data given as parameter to connected applications.
|
|
Before evaluating the parameter, the request processing is suspended
|
|
using tm module (using the t_suspend()/t_continue() framework). The
|
|
routing of the SIP request can be continued once
|
|
event_route[evapi:message-received] is triggered. After
|
|
evapi_async_relay() returns true, no relaying should happen in
|
|
request_route(), it should be followed by exit;.
|
|
|
|
The format on the network is netstring with evdata payload if
|
|
netstring_format parameter is set to 1 or bare evdata if
|
|
netstring_format parameter is set to 0.
|
|
|
|
This function can be used from REQUEST_ROUTE.
|
|
|
|
Example 1.6. evapi_async_relay usage
|
|
...
|
|
evapi_async_relay("{ \"event\": \"suspend\",\n \"data\":"
|
|
" { \"index\": \"$T(id_index)\", \"label\": \"$T(id_label)\" }\n}");
|
|
...
|
|
|
|
4.3. evapi_close()
|
|
|
|
Close evapi current client connection.
|
|
|
|
This function can be used from ANY_ROUTE.
|
|
|
|
Example 1.7. evapi_evapi usage
|
|
...
|
|
event_route[evapi:connection-new] {
|
|
if($evapi(srcaddr)!="127.0.0.1") {
|
|
evapi_close();
|
|
exit;
|
|
}
|
|
}
|
|
...
|
|
|
|
5. Event routes
|
|
|
|
5.1. evapi:connection-new
|
|
5.2. evapi:connection-closed
|
|
5.3. evapi:message-received
|
|
|
|
5.1. evapi:connection-new
|
|
|
|
If defined, the module calls event_route[evapi:connection-new] when a
|
|
new client is connected.
|
|
...
|
|
event_route[evapi:connection-new] {
|
|
xlog("new connection from $evapi(srcaddr):$evapi(srcport)\n");
|
|
}
|
|
...
|
|
|
|
5.2. evapi:connection-closed
|
|
|
|
If defined, the module calls event_route[evapi:connection-closed] when
|
|
a client connection is closed.
|
|
...
|
|
event_route[evapi:connection-closed] {
|
|
xlog("connection closed by $evapi(srcaddr):$evapi(srcport)\n");
|
|
}
|
|
...
|
|
|
|
5.3. evapi:message-received
|
|
|
|
If defined, the module calls event_route[evapi:message-received] when a
|
|
message is received from a client.
|
|
...
|
|
event_route[evapi:message-received] {
|
|
xlog("received [$evapi(msg)] from $evapi(srcaddr):$evapi(srcport)\n");
|
|
}
|
|
...
|
|
|
|
6. Exported pseudo-variables
|
|
|
|
* $evapi(srcaddr) - source ip
|
|
* $evapi(srcport) - source port
|
|
* $evapi(msg) - received event message
|
|
* $evapi(conidx) - internal connection index
|
|
|
|
Exported pseudo-variables are documented at
|
|
http://www.kamailio.org/wiki/.
|