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.
312 lines
8.0 KiB
312 lines
8.0 KiB
utils
|
|
|
|
Juha Heinanen
|
|
|
|
TutPro Inc.
|
|
|
|
Copyright © 2008 Juha Heinanen
|
|
__________________________________________________________________
|
|
|
|
Table of Contents
|
|
|
|
1. Admin Guide
|
|
|
|
1. Overview
|
|
2. Dependencies
|
|
|
|
2.1. Kamailio Modules
|
|
2.2. External Libraries or Applications
|
|
|
|
3. Exported Parameters
|
|
|
|
3.1. http_query_timeout (int)
|
|
3.2. forward_active (int)
|
|
3.3. pres_db_url (string)
|
|
3.4. xcap_table (string)
|
|
|
|
4. Exported Functions
|
|
|
|
4.1. http_query(url, result)
|
|
4.2. xcap_auth_status(watcher_uri, presentity_uri)
|
|
|
|
5. MI Commands
|
|
|
|
5.1. forward_list
|
|
5.2. forward_switch
|
|
5.3. forward_filter
|
|
5.4. forward_proxy
|
|
|
|
6. Configuration syntax
|
|
|
|
List of Examples
|
|
|
|
1.1. Set http_query_timeout parameter
|
|
1.2. Set forward_active parameter
|
|
1.3. Set pres_db_url parameter
|
|
1.4. Set xcap_table parameter
|
|
1.5. http_query() usage
|
|
1.6. xcap_auth_status() usage
|
|
1.7. forward_list usage
|
|
1.8. forward_switch usage
|
|
1.9. forward_filter usage
|
|
1.10. forward_proxy usage
|
|
|
|
Chapter 1. Admin Guide
|
|
|
|
Table of Contents
|
|
|
|
1. Overview
|
|
2. Dependencies
|
|
|
|
2.1. Kamailio Modules
|
|
2.2. External Libraries or Applications
|
|
|
|
3. Exported Parameters
|
|
|
|
3.1. http_query_timeout (int)
|
|
3.2. forward_active (int)
|
|
3.3. pres_db_url (string)
|
|
3.4. xcap_table (string)
|
|
|
|
4. Exported Functions
|
|
|
|
4.1. http_query(url, result)
|
|
4.2. xcap_auth_status(watcher_uri, presentity_uri)
|
|
|
|
5. MI Commands
|
|
|
|
5.1. forward_list
|
|
5.2. forward_switch
|
|
5.3. forward_filter
|
|
5.4. forward_proxy
|
|
|
|
6. Configuration syntax
|
|
|
|
1. Overview
|
|
|
|
This module implements various utility functions that are not SIP
|
|
related.
|
|
|
|
Function http_query allows Kamailio to issue an HTTP GET request and
|
|
get access to parts of the reply.
|
|
|
|
The forward functionality allows Kamailio to configure forwarding at
|
|
runtime with FIFO commands. The forwarding is executed in the pre
|
|
script call back and therefore handled before the routing script is
|
|
executed on the current message. The callback is not installed on
|
|
default, thus this functionality has no runtime overhead when its
|
|
deactivated.
|
|
|
|
Function xcap_auth_status can be used to check from presence server
|
|
database, if watcher is authorized to subscribe event "presence" of
|
|
presentity.
|
|
|
|
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:
|
|
* None.
|
|
|
|
2.2. External Libraries or Applications
|
|
|
|
The following libraries or applications must be installed before
|
|
running Kamailio with this module loaded:
|
|
* libcurl.
|
|
|
|
3. Exported Parameters
|
|
|
|
3.1. http_query_timeout (int)
|
|
3.2. forward_active (int)
|
|
3.3. pres_db_url (string)
|
|
3.4. xcap_table (string)
|
|
|
|
3.1. http_query_timeout (int)
|
|
|
|
Defines in seconds how long Kamailio waits response from HTTP server.
|
|
|
|
Default value is "4".
|
|
|
|
Example 1.1. Set http_query_timeout parameter
|
|
...
|
|
modparam("utils", "http_query_timeout", 2)
|
|
...
|
|
|
|
3.2. forward_active (int)
|
|
|
|
Defines if the forwarding callback should be installed.
|
|
|
|
Default value is "0".
|
|
|
|
Example 1.2. Set forward_active parameter
|
|
...
|
|
modparam("utils", "forward_active", 1)
|
|
...
|
|
|
|
3.3. pres_db_url (string)
|
|
|
|
Defines presence server database URL. If not given, xcap_auth_status
|
|
function is disabled.
|
|
|
|
There is no default value.
|
|
|
|
Example 1.3. Set pres_db_url parameter
|
|
...
|
|
modparam("utils", "pres_db_url", "mysql://foo:secret@localhost/pres")
|
|
...
|
|
|
|
3.4. xcap_table (string)
|
|
|
|
Defines name of xcap table in presence server database.
|
|
|
|
Default value is "xcap".
|
|
|
|
Example 1.4. Set xcap_table parameter
|
|
...
|
|
modparam("utils", "xcap_table", "pres_xcap")
|
|
...
|
|
|
|
4. Exported Functions
|
|
|
|
4.1. http_query(url, result)
|
|
4.2. xcap_auth_status(watcher_uri, presentity_uri)
|
|
|
|
4.1. http_query(url, result)
|
|
|
|
Sends HTTP GET request according to URL given in "url" parameter, which
|
|
is a string that may contain pseudo variables.
|
|
|
|
If HTTP server returns a class 2xx or 3xx reply, first line of reply's
|
|
body (if any) is stored in "result" parameter, which must be a writable
|
|
pseudo variable.
|
|
|
|
Function returns reply code of HTTP reply or -1 if something went
|
|
wrong.
|
|
|
|
This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE,
|
|
FAILURE_ROUTE, and BRANCH_ROUTE.
|
|
|
|
Example 1.5. http_query() usage
|
|
...
|
|
http_query("http://tutpro.com/index.php?r_uri=$(ru{s.escape.param})&f_uri=$(fu{s
|
|
.escape.param})",
|
|
"$var(result)")
|
|
switch ($retcode) {
|
|
...
|
|
}
|
|
...
|
|
|
|
4.2. xcap_auth_status(watcher_uri, presentity_uri)
|
|
|
|
Function checks from presence server database if watcher is authorized
|
|
to subscribe event "presence" of presentity. Sphere checking is not
|
|
included.
|
|
|
|
Both watcher_uri and presentity_uri are pseudo variables. Function
|
|
returns ACTIVE_STATUS, if subscription is allowed and PENDING_STATUS,
|
|
TERMINATED_STATUS, or WAITING_STATUS otherwise. See
|
|
presence/subscribe.h for the corresponding integer codes. In case of
|
|
error, function returns -1.
|
|
|
|
Function can be used from REQUEST_ROUTE.
|
|
|
|
Example 1.6. xcap_auth_status() usage
|
|
...
|
|
if (method=="MESSAGE") {
|
|
xcap_auth_status("$fu", $ru");
|
|
if ($retcode == 1) {
|
|
t_relay();
|
|
} else {
|
|
send_reply("403", "Forbidden");
|
|
}
|
|
}
|
|
...
|
|
|
|
5. MI Commands
|
|
|
|
5.1. forward_list
|
|
5.2. forward_switch
|
|
5.3. forward_filter
|
|
5.4. forward_proxy
|
|
|
|
5.1. forward_list
|
|
|
|
List active forward rules.
|
|
|
|
No parameters.
|
|
|
|
Example 1.7. forward_list usage
|
|
...
|
|
kamctl fifo forward_list
|
|
id switch filter proxy
|
|
0 off REGISTER:INVITE:SUBSCRIBE host-a.domain-a:5060
|
|
...
|
|
|
|
5.2. forward_switch
|
|
|
|
This command can be used to activate or deactivate forwarding rules.
|
|
The syntax of this configuration string is described in 1.6.
|
|
(switch_setting_list).
|
|
|
|
Example 1.8. forward_switch usage
|
|
...
|
|
kamctl fifo sp_forward_switch 0=on
|
|
...
|
|
|
|
5.3. forward_filter
|
|
|
|
Can be used to specify the filter for a certain id. Messages will only
|
|
be forwarded if one of the filters matches the message.
|
|
|
|
There are special filters and regular filters. Special filters are:
|
|
* REQUEST (matches on every request)
|
|
* REPLY (matches on every reply)
|
|
|
|
Regular filters are arbitrary strings not containing the delimiter ':'.
|
|
They are matched against the request method names of the sip messages.
|
|
The syntax of this configuration string is described in 1.6.
|
|
(filter_setting_list).
|
|
|
|
Example 1.9. forward_filter usage
|
|
...
|
|
kamctl fifo sp_forward_filter 0=REGISTER:INVITE
|
|
...
|
|
|
|
5.4. forward_proxy
|
|
|
|
This command can be used to configure forwarding rules. Specifies the
|
|
destination for a certain id. Messages will be forwarded to this
|
|
destination if the preconditions hold (matching id, filter, and
|
|
switch). The syntax of this configuration string is described in 1.6.
|
|
(proxy_setting_list).
|
|
|
|
Example 1.10. forward_proxy usage
|
|
...
|
|
kamctl fifo sp_forward_proxy 0=host-c.domain-c:5060
|
|
...
|
|
|
|
6. Configuration syntax
|
|
|
|
This grammar specify the usable configuration syntax
|
|
* switch_setting_list ::= switch_setting { "," switch_setting }
|
|
* filter_setting_list ::= switch_setting { "," switch_setting }
|
|
* proxy_setting_list ::= proxy_setting { "," proxy_setting }
|
|
* switch_setting ::= id "=" switch
|
|
* filter_setting ::= id "=" filter_list
|
|
* proxy_setting ::= id "=" proxy
|
|
* switch ::= ( "off" | "on" )
|
|
* filter_list ::= filter { ":" filter }
|
|
* proxy ::= host ":" port
|
|
* filter ::= ( special_filter | regular_filter )
|
|
* special_filter ::= ( "REQUEST" | "REPLY" )
|
|
* regular_filter ::= ? [^:]* ?
|
|
* host ::= char { char }
|
|
* char ::= ? A-Za-z0-9.-_ ?
|
|
* id ::= number
|
|
* port ::= number
|
|
* number ::= digit {digit}
|
|
* digit ::= ? 0-9 ?
|