modules/pv/README
9706aace
 Pseudo-Variables Module
 
c7686364
 Daniel-Constantin Mierla
9706aace
 
    asipto.com
    <daniel@asipto.com>
 
 Edited by
 
 Daniel-Constantin Mierla
 
    <daniel@asipto.com>
 
007ca3c3
    Copyright � 2008-2011 Daniel-Constantin Mierla (asipto.com)
c8fb53ac
 
007ca3c3
    Copyright � 2011 Juha Heinanen
7c940fa7
 
    Copyright � 2013 Olle E. Johansson, Edvina AB
12a8f3f8
      __________________________________________________________________
9706aace
 
    Table of Contents
 
    1. Admin Guide
 
12a8f3f8
         1. Overview
         2. Dependencies
9706aace
 
12a8f3f8
               2.1. Kamailio Modules
               2.2. External Libraries or Applications
9706aace
 
ba7961bb
         3. Parameters
8dfcdd20
 
12a8f3f8
               3.1. shvset (string)
               3.2. varset (string)
941c2ca3
               3.3. avp_aliases (string)
8dfcdd20
 
ba7961bb
         4. Functions
8dfcdd20
 
12a8f3f8
               4.1. pv_isset(pvar)
               4.2. pv_unset(pvar)
c8fb53ac
               4.3. is_int(pvar)
007ca3c3
               4.4. typeof(pvar, vtype)
               4.5. not_empty(pvar)
12a8f3f8
 
         5. MI Commands
 
               5.1. shv_set
               5.2. shv_get
8dfcdd20
 
ab1d5bf5
         6. RPC Commands
 
               6.1. pv.shvSet
               6.2. pv.shvGet
 
8dfcdd20
    List of Examples
 
    1.1. shvset parameter usage
    1.2. varset parameter usage
941c2ca3
    1.3. avp_aliases parameter usage
    1.4. pv_isset usage
    1.5. pv_unset usage
c8fb53ac
    1.6. is_int() usage
007ca3c3
    1.7. typeof() usage
    1.8. not_empty() usage
    1.9. shv_set usage
    1.10. shv_get usage
9706aace
 
 Chapter 1. Admin Guide
 
12a8f3f8
    Table of Contents
 
    1. Overview
    2. Dependencies
 
         2.1. Kamailio Modules
         2.2. External Libraries or Applications
 
ba7961bb
    3. Parameters
12a8f3f8
 
         3.1. shvset (string)
         3.2. varset (string)
941c2ca3
         3.3. avp_aliases (string)
12a8f3f8
 
ba7961bb
    4. Functions
9706aace
 
12a8f3f8
         4.1. pv_isset(pvar)
         4.2. pv_unset(pvar)
c8fb53ac
         4.3. is_int(pvar)
007ca3c3
         4.4. typeof(pvar, vtype)
         4.5. not_empty(pvar)
12a8f3f8
 
    5. MI Commands
 
         5.1. shv_set
         5.2. shv_get
 
ab1d5bf5
    6. RPC Commands
 
         6.1. pv.shvSet
         6.2. pv.shvGet
 
12a8f3f8
 1. Overview
 
    This module collects the core pseudo-variables that can be used in
    configuration file. They are listed in Dokuwiki:
ebeb18ff
    http://www.kamailio.org/wiki/, in Pseudo-Variables section
9706aace
 
12a8f3f8
 2. Dependencies
9706aace
 
12a8f3f8
    2.1. Kamailio Modules
    2.2. External Libraries or Applications
 
 2.1. Kamailio Modules
9706aace
 
    The following modules must be loaded before this module:
      * No dependencies on other Kamailio modules.
 
12a8f3f8
 2.2. External Libraries or Applications
9706aace
 
12a8f3f8
    The following libraries or applications must be installed before
    running Kamailio with this module loaded:
9706aace
      * None.
 
ba7961bb
 3. Parameters
12a8f3f8
 
    3.1. shvset (string)
    3.2. varset (string)
941c2ca3
    3.3. avp_aliases (string)
9706aace
 
12a8f3f8
 3.1. shvset (string)
8dfcdd20
 
12a8f3f8
    Set the value of a shared variable ($shv(name)). The parameter can be
    set many times.
8dfcdd20
 
12a8f3f8
    The value of the parameter has the format: _name_ '=' _type_ ':'
    _value_
8dfcdd20
      * _name_: shared variable name
      * _type_: type of the value
007ca3c3
           + "i": integer value
           + "s": string value
8dfcdd20
      * _value_: value to be set
 
007ca3c3
    Default value is "NULL".
8dfcdd20
 
    Example 1.1. shvset parameter usage
 ...
 modparam("pv", "shvset", "debug=i:1")
 modparam("pv", "shvset", "pstngw=s:sip:10.10.10.10")
 ...
 
12a8f3f8
 3.2. varset (string)
8dfcdd20
 
12a8f3f8
    Set the value of a script variable ($var(name)). The parameter can be
    set many times.
8dfcdd20
 
12a8f3f8
    The value of the parameter has the format: _name_ '=' _type_ ':'
    _value_
8dfcdd20
      * _name_: shared variable name
      * _type_: type of the value
007ca3c3
           + "i": integer value
           + "s": string value
8dfcdd20
      * _value_: value to be set
 
007ca3c3
    Default value is "NULL".
8dfcdd20
 
    Example 1.2. varset parameter usage
 ...
 modparam("pv", "varset", "init=i:1")
 modparam("pv", "varset", "gw=s:sip:11.11.11.11;transport=tcp")
 ...
9706aace
 
941c2ca3
 3.3. avp_aliases (string)
 
    Define aliases for PV AVP names.
 
    Default value is NULL.
 
    Example 1.3. avp_aliases parameter usage
 ...
 modparam("pv","avp_aliases","email=s:email_addr;tmp=i:100")
 ...
 
ba7961bb
 4. Functions
12a8f3f8
 
    4.1. pv_isset(pvar)
    4.2. pv_unset(pvar)
c8fb53ac
    4.3. is_int(pvar)
007ca3c3
    4.4. typeof(pvar, vtype)
    4.5. not_empty(pvar)
12a8f3f8
 
 4.1. pv_isset(pvar)
 
    Return true if a PV value is different than 'null'.
 
    Meaning of the parameters is as follows:
      * pvar - pvar identifier.
 
    This function can be used from ANY_ROUTE.
 
941c2ca3
    Example 1.4. pv_isset usage
12a8f3f8
 ...
4684743d
 if(pv_isset("$avp(s:x)"))
12a8f3f8
 {
     ...
 }
 ...
 
 4.2. pv_unset(pvar)
 
    Unset the value of the PV (e.g., delete AVP, set to null).
 
    Meaning of the parameters is as follows:
      * pvar - pvar identifier.
 
    This function can be used from ANY_ROUTE.
 
941c2ca3
    Example 1.5. pv_unset usage
12a8f3f8
 ...
4684743d
 pv_unset("$avp(s:x)");
12a8f3f8
 ...
9706aace
 
ebeb18ff
 4.3. is_int(pvar)
c8fb53ac
 
    Function checks if pvar argument contains integer value and returns 1
    if it does and -1 otherwise.
 
    Function can be used from all kinds of routes.
 
    Example 1.6. is_int() usage
 ...
 if (is_int("$var(foo)")) {
     xlog("L_INFO", "variable foo contains integer value\n");
 }
 ...
 
ebeb18ff
 4.4. typeof(pvar, vtype)
007ca3c3
 
    Returns true if the type of pseudo-variable matches the second
    parameter. The second parameter can be: 'int' - type is integer; 'str'
    - type is string; 'null' - type is null.
 
    Function can be used from ANYROUTE.
 
    Example 1.7. typeof() usage
 ...
68a650ef
 if (typeof("$var(foo)", "str")) {
007ca3c3
     xdbg("variable foo is a string\n");
 }
 ...
 
ebeb18ff
 4.5. not_empty(pvar)
007ca3c3
 
    Returns true if the pseudo-variables has the type string and is not
    empty value.
 
    Function can be used from all kinds of routes.
 
    Example 1.8. not_empty() usage
 ...
 if (not_empty("$var(foo)")) {
     append_hf("X-Foo: $var(foo)\r\n");
 }
 ...
 
12a8f3f8
 5. MI Commands
8dfcdd20
 
12a8f3f8
    5.1. shv_set
    5.2. shv_get
8dfcdd20
 
12a8f3f8
 5.1. shv_set
8dfcdd20
 
    Set the value of a shared variable ($shv(name)).
 
    Parameters:
      * _name_: shared variable name
      * _type_: type of the value
007ca3c3
           + "int": integer value
           + "str": string value
8dfcdd20
      * _value_: value to be set
 
    MI FIFO Command Format:
                 :shv_set:_reply_fifo_file_
                 _name_
                 _type_
                 _value_
                 _empty_line_
 
007ca3c3
    Example 1.9. shv_set usage
8dfcdd20
 ...
 $ kamctl fifo shv_set debug int 0
 ...
 
12a8f3f8
 5.2. shv_get
8dfcdd20
 
    Get the value of a shared variable ($shv(name)).
 
    Parameters:
12a8f3f8
      * _name_: shared variable name. If this parameter is missing, all
        shared variables are returned.
8dfcdd20
 
    MI FIFO Command Format:
                 :shv_get:_reply_fifo_file_
                 _name_
                 _empty_line_
 
007ca3c3
    Example 1.10. shv_get usage
8dfcdd20
 ...
 $ kamctl fifo shv_get debug
 $ kamctl fifo shv_get
 ...
ab1d5bf5
 
 6. RPC Commands
 
    6.1. pv.shvSet
    6.2. pv.shvGet
 
 6.1. pv.shvSet
 
    Set the value of a shared variable ($shv(name)).
 
    Parameters:
      * _name_: shared variable name
      * _type_: type of the value
           + "int": integer value
           + "str": string value
      * _value_: value to be set
 
 6.2. pv.shvGet
 
    Get the value of a shared variable ($shv(name)).
 
    Parameters:
      * _name_: shared variable name
 
    If no name is given, all shared variables are listed