src/modules/utils/README
3837c6d0
 utils
 
 Juha Heinanen
 
    TutPro Inc.
 
feba7dd8
 Carsten Bock
 
    ng-voice GmbH
 
9cb2a163
    Copyright © 2008-2009 Juha Heinanen
feba7dd8
 
9cb2a163
    Copyright © 2013-2015 Carsten Bock, ng-voice GmbH
b64b67df
      __________________________________________________________________
3837c6d0
 
    Table of Contents
 
    1. Admin Guide
 
b64b67df
         1. Overview
         2. Dependencies
3837c6d0
 
b64b67df
               2.1. Kamailio Modules
               2.2. External Libraries or Applications
3837c6d0
 
ba7961bb
         3. Parameters
3837c6d0
 
29922546
               3.1. forward_active (int)
               3.2. pres_db_url (string)
               3.3. xcap_table (string)
3837c6d0
 
ba7961bb
         4. Functions
3837c6d0
 
29922546
               4.1. xcap_auth_status(watcher_uri, presentity_uri)
3837c6d0
 
b64b67df
         5. MI Commands
bb356975
 
b64b67df
               5.1. forward_list
               5.2. forward_switch
               5.3. forward_filter
               5.4. forward_proxy
bb356975
 
b64b67df
         6. Configuration syntax
bb356975
 
3837c6d0
    List of Examples
 
29922546
    1.1. Set forward_active parameter
    1.2. Set pres_db_url parameter
    1.3. Set xcap_table parameter
    1.4. xcap_auth_status() usage
    1.5. forward_list usage
    1.6. forward_switch usage
    1.7. forward_filter usage
    1.8. forward_proxy usage
3837c6d0
 
 Chapter 1. Admin Guide
 
b64b67df
    Table of Contents
 
    1. Overview
    2. Dependencies
 
         2.1. Kamailio Modules
         2.2. External Libraries or Applications
 
ba7961bb
    3. Parameters
b64b67df
 
29922546
         3.1. forward_active (int)
         3.2. pres_db_url (string)
         3.3. xcap_table (string)
b64b67df
 
ba7961bb
    4. Functions
b64b67df
 
29922546
         4.1. xcap_auth_status(watcher_uri, presentity_uri)
b64b67df
 
    5. MI Commands
 
         5.1. forward_list
         5.2. forward_switch
         5.3. forward_filter
         5.4. forward_proxy
3837c6d0
 
b64b67df
    6. Configuration syntax
3837c6d0
 
b64b67df
 1. Overview
3837c6d0
 
b64b67df
    This module implements various utility functions that are not SIP
    related.
bb356975
 
b64b67df
    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
9cb2a163
    database, if watcher is authorized to subscribe event “presence” of
b64b67df
    presentity.
 
 2. Dependencies
 
    2.1. Kamailio Modules
    2.2. External Libraries or Applications
 
 2.1. Kamailio Modules
3837c6d0
 
    The following modules must be loaded before this module:
c437c250
      * a database module if xcap_auth_status function is enabled.
3837c6d0
 
b64b67df
 2.2. External Libraries or Applications
3837c6d0
 
b64b67df
    The following libraries or applications must be installed before
    running Kamailio with this module loaded:
29922546
      * none.
3837c6d0
 
ba7961bb
 3. Parameters
b64b67df
 
29922546
    3.1. forward_active (int)
    3.2. pres_db_url (string)
    3.3. xcap_table (string)
bc74d54a
 
29922546
 3.1. forward_active (int)
bb356975
 
    Defines if the forwarding callback should be installed.
 
9cb2a163
    Default value is “0” - disabled.
bb356975
 
29922546
    Example 1.1. Set forward_active parameter
bb356975
                                         ...
b64b67df
                                         modparam("utils", "forward_active", 1)
bb356975
                                         ...
 
29922546
 3.2. pres_db_url (string)
b64b67df
 
1ab39cf8
    Defines presence server database URL. If not given, the
    xcap_auth_status function is disabled.
b64b67df
 
    There is no default value.
 
29922546
    Example 1.2. Set pres_db_url parameter
b64b67df
 ...
 modparam("utils", "pres_db_url", "mysql://foo:secret@localhost/pres")
 ...
 
29922546
 3.3. xcap_table (string)
b64b67df
 
1ab39cf8
    Defines the name of the xcap table in the presence server database. See
    the xcap_server module documentation for more information.
b64b67df
 
9cb2a163
    Default value is “xcap”.
b64b67df
 
29922546
    Example 1.3. Set xcap_table parameter
b64b67df
 ...
 modparam("utils", "xcap_table", "pres_xcap")
 ...
 
ba7961bb
 4. Functions
b64b67df
 
29922546
    4.1. xcap_auth_status(watcher_uri, presentity_uri)
3837c6d0
 
29922546
 4.1.  xcap_auth_status(watcher_uri, presentity_uri)
b64b67df
 
1ab39cf8
    Function checks in the presence server database if a watcher is
9cb2a163
    authorized to subscribe to event “presence” of presentity. Sphere
1ab39cf8
    checking is not included.
b64b67df
 
1ab39cf8
    Both watcher_uri and presentity_uri are pseudo variables. The function
    returns ACTIVE_STATUS, if a subscription is allowed and PENDING_STATUS,
b64b67df
    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.
 
29922546
    Example 1.4. xcap_auth_status() usage
b64b67df
 ...
 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
bb356975
 
b64b67df
 5.1. forward_list
bb356975
 
    List active forward rules.
 
    No parameters.
 
29922546
    Example 1.5. forward_list usage
bb356975
 ...
 kamctl fifo forward_list
 id switch                         filter proxy
  0    off      REGISTER:INVITE:SUBSCRIBE host-a.domain-a:5060
 ...
 
b64b67df
 5.2. forward_switch
bb356975
 
b64b67df
    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).
bb356975
 
29922546
    Example 1.6. forward_switch usage
bb356975
 ...
a7522f0d
 kamctl fifo forward_switch 0=on
bb356975
 ...
 
b64b67df
 5.3. forward_filter
bb356975
 
b64b67df
    Can be used to specify the filter for a certain id. Messages will only
    be forwarded if one of the filters matches the message.
bb356975
 
b64b67df
    There are special filters and regular filters. Special filters are:
bb356975
      * REQUEST (matches on every request)
      * REPLY (matches on every reply)
 
b64b67df
    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).
bb356975
 
29922546
    Example 1.7. forward_filter usage
bb356975
 ...
a7522f0d
 kamctl fifo forward_filter 0=REGISTER:INVITE
bb356975
 ...
 
b64b67df
 5.4. forward_proxy
bb356975
 
b64b67df
    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).
bb356975
 
29922546
    Example 1.8. forward_proxy usage
bb356975
 ...
a7522f0d
 kamctl fifo forward_proxy 0=host-c.domain-c:5060
bb356975
 ...
 
b64b67df
 6. Configuration syntax
bb356975
 
    This grammar specify the usable configuration syntax
b64b67df
      * switch_setting_list ::= switch_setting { "," switch_setting }
      * filter_setting_list ::= switch_setting { "," switch_setting }
bb356975
      * 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 ?