siputils

Hardy Kahl

   1&1 Internet AG

Henning Westerholt

   1&1 Internet AG

Nils Ohlmeier

   FhG Fokus

Jan Janak

   FhG FOKUS

Daniel-Constantin Mierla

   asipto.com

Gabriel Vasile

   FhG FOKUS

Juha Heinanen

   TutPro Inc.

Edited by

Jan Janak

Bogdan-Andrei Iancu

Gabriel Vasile

Eik Rentzow

   Copyright © 2008, 2005, 2003 1&1 Internet AG, FhG Fokus, Voice Sistem
   SRL
     __________________________________________________________________

   Table of Contents

   1. Admin Guide

        1. Overview
        2. Dependencies

              2.1. Kamailio Modules
              2.2. External Libraries or Applications

        3. Parameters

              3.1. options_accept (string)
              3.2. options_accept_encoding (string)
              3.3. contact_flds_separator (string)
              3.4. options_accept_language (string)
              3.5. options_support (string)
              3.6. rpid_prefix (string)
              3.7. rpid_suffix (string)
              3.8. rpid_avp (string)
              3.9. e164_max_len (int)

        4. Functions

              4.1. options_reply()
              4.2. is_user(username)
              4.3. has_totag()
              4.4. uri_param(param)
              4.5. uri_param(param, value)
              4.6. uri_param_any(param)
              4.7. add_uri_param(param)
              4.8. get_uri_param(name, var)
              4.9. uri_param_rm(param)
              4.10. tel2sip(uri, hostpart, result)
              4.11. tel2sip2(uri, hostpart, result)
              4.12. is_e164(pseudo-variable)
              4.13. is_uri_user_e164(pseudo-variable)
              4.14. is_uri(pseudo-variable)
              4.15. is_tel_number(tval)
              4.16. is_numeric(tval)
              4.17. is_alphanum(tval)
              4.18. is_alphanumex(tval, eset)
              4.19. encode_contact(encoding_prefix, hostpart)
              4.20. decode_contact()
              4.21. decode_contact_header()
              4.22. cmp_uri(str1, str2)
              4.23. cmp_aor(str1, str2)
              4.24. cmp_hdr_name(str1, str2)
              4.25. append_rpid_hf()
              4.26. append_rpid_hf(prefix, suffix)
              4.27. is_rpid_user_e164()
              4.28. set_uri_user(uri, user)
              4.29. set_uri_host(uri, host)
              4.30. is_request()
              4.31. is_reply()
              4.32. is_sip()
              4.33. is_http()
              4.34. is_gruu([uri])
              4.35. is_supported(option)
              4.36. is_first_hop([mode])
              4.37. sip_p_charging_vector(flags)
              4.38. contact_param_encode(pname, saddr)
              4.39. contact_param_encode_alias(pname, saddr)
              4.40. contact_param_decode(pname)
              4.41. contact_param_decode_uri(pname)
              4.42. contact_param_rm(pname)
              4.43. contact_param_check(pname)
              4.44. hdr_date_check(tdiff)
              4.45. sip_parse_headers()

        5. Exported pseudo-variables

              5.1. $pcv(all)
              5.2. $pcv(value)
              5.3. $pcv(genaddr)
              5.4. $pcv(orig)
              5.5. $pcv(term)
              5.6. $pcv(status)

   List of Examples

   1.1. Set options_accept parameter
   1.2. Set options_accept_encoding parameter
   1.3. Set contact_flds_separator parameter
   1.4. Set options_accept_language parameter
   1.5. Set options_support parameter
   1.6. rpid_prefix parameter example
   1.7. rpid_suffix parameter example
   1.8. rpid_avp parameter example
   1.9. e164_max_len parameter example
   1.10. options_reply usage
   1.11. is_user usage
   1.12. has_totag usage
   1.13. uri_param usage
   1.14. uri_param usage
   1.15. uri_param_any usage
   1.16. add_uri_param usage
   1.17. add_uri_param usage
   1.18. uri_param_rm usage
   1.19. tel2sip usage
   1.20. tel2sip2 usage
   1.21. is_e164 usage
   1.22. is_uri_user_e164 usage
   1.23. is_uri usage
   1.24. is_tel_number usage
   1.25. is_numeric usage
   1.26. is_alphanum usage
   1.27. is_alphanumex usage
   1.28. encode_contact usage
   1.29. decode_contact usage
   1.30. decode_contact_header usage
   1.31. cmp_uri usage
   1.32. cmp_aor usage
   1.33. cmp_hdr_name usage
   1.34. append_rpid_hf usage
   1.35. append_rpid_hf(prefix, suffix) usage
   1.36. is_rpid_user_e164 usage
   1.37. set_uri_user usage
   1.38. set_uri_host usage
   1.39. is_request usage
   1.40. is_reply usage
   1.41. is_sip usage
   1.42. is_http usage
   1.43. is_gruu() usage
   1.44. is_supported() usage
   1.45. is_first_hop() usage
   1.46. sip_p_charging_vector() usage
   1.47. contact_param_encode usage
   1.48. contact_param_encode_alias usage
   1.49. contact_param_decode usage
   1.50. contact_param_decode_ruri usage
   1.51. contact_param_rm usage
   1.52. contact_param_check usage
   1.53. hdr_date_check usage
   1.54. sip_parse_headers 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. options_accept (string)
        3.2. options_accept_encoding (string)
        3.3. contact_flds_separator (string)
        3.4. options_accept_language (string)
        3.5. options_support (string)
        3.6. rpid_prefix (string)
        3.7. rpid_suffix (string)
        3.8. rpid_avp (string)
        3.9. e164_max_len (int)

   4. Functions

        4.1. options_reply()
        4.2. is_user(username)
        4.3. has_totag()
        4.4. uri_param(param)
        4.5. uri_param(param, value)
        4.6. uri_param_any(param)
        4.7. add_uri_param(param)
        4.8. get_uri_param(name, var)
        4.9. uri_param_rm(param)
        4.10. tel2sip(uri, hostpart, result)
        4.11. tel2sip2(uri, hostpart, result)
        4.12. is_e164(pseudo-variable)
        4.13. is_uri_user_e164(pseudo-variable)
        4.14. is_uri(pseudo-variable)
        4.15. is_tel_number(tval)
        4.16. is_numeric(tval)
        4.17. is_alphanum(tval)
        4.18. is_alphanumex(tval, eset)
        4.19. encode_contact(encoding_prefix, hostpart)
        4.20. decode_contact()
        4.21. decode_contact_header()
        4.22. cmp_uri(str1, str2)
        4.23. cmp_aor(str1, str2)
        4.24. cmp_hdr_name(str1, str2)
        4.25. append_rpid_hf()
        4.26. append_rpid_hf(prefix, suffix)
        4.27. is_rpid_user_e164()
        4.28. set_uri_user(uri, user)
        4.29. set_uri_host(uri, host)
        4.30. is_request()
        4.31. is_reply()
        4.32. is_sip()
        4.33. is_http()
        4.34. is_gruu([uri])
        4.35. is_supported(option)
        4.36. is_first_hop([mode])
        4.37. sip_p_charging_vector(flags)
        4.38. contact_param_encode(pname, saddr)
        4.39. contact_param_encode_alias(pname, saddr)
        4.40. contact_param_decode(pname)
        4.41. contact_param_decode_uri(pname)
        4.42. contact_param_rm(pname)
        4.43. contact_param_check(pname)
        4.44. hdr_date_check(tdiff)
        4.45. sip_parse_headers()

   5. Exported pseudo-variables

        5.1. $pcv(all)
        5.2. $pcv(value)
        5.3. $pcv(genaddr)
        5.4. $pcv(orig)
        5.5. $pcv(term)
        5.6. $pcv(status)

1. Overview

   This module implements various functions and checks related to SIP
   message handling and URI handling.

   This module also provides a function to answer OPTIONS requests which
   are directed to the server itself. This means an OPTIONS request which
   has the address of the server in the request URI, and no username in
   the URI. The request will be answered with a 200 OK with the
   capabilities of the server.

   To answer OPTIONS request directed to your server is the easiest way
   for is-alive-tests on the SIP (application) layer from remote (similar
   to ICMP echo requests, also known as “ping”, on the network layer).

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:
     * sl -- Stateless replies.

2.2. External Libraries or Applications

   The following libraries or applications must be installed before
   running Kamailio with this module loaded:
     * None.

3. Parameters

   3.1. options_accept (string)
   3.2. options_accept_encoding (string)
   3.3. contact_flds_separator (string)
   3.4. options_accept_language (string)
   3.5. options_support (string)
   3.6. rpid_prefix (string)
   3.7. rpid_suffix (string)
   3.8. rpid_avp (string)
   3.9. e164_max_len (int)

3.1. options_accept (string)

   This parameter is the content of the Accept header field. Note: it is
   not clearly written in RFC3261 if a proxy should accept any content
   (the default “*/*”) because it does not care about content. Or if it
   does not accept any content, which is “”.

   Default value is “*/*”.

   Example 1.1. Set options_accept parameter
...
modparam("siputils", "options_accept", "application/*")
...

3.2. options_accept_encoding (string)

   This parameter is the content of the Accept-Encoding header field.
   Please do not change the default value because Kamailio does not
   support any encodings yet.

   Default value is “”.

   Example 1.2. Set options_accept_encoding parameter
...
modparam("siputils", "options_accept_encoding", "gzip")
...

3.3. contact_flds_separator (string)

   First char of this parameter is used as separator for encoding/decoding
   Contact header.

Warning

   First char of this field must be set to a value which is not used
   inside username, password or other fields of contact. Otherwise it is
   possible for the decoding step to fail/produce wrong results.

   Default value is “*”.

   Example 1.3. Set contact_flds_separator parameter
...
modparam("siputils", "contact_flds_separator", "-")
...

   then an encoded uri might look
   sip:user-password-ip-port-protocol@PublicIP

3.4. options_accept_language (string)

   This parameter is the content of the Accept-Language header field. You
   can set any language code which you prefer for error descriptions from
   other devices, but presumably there are not many devices around which
   support other languages than the default English.

   Default value is “en”.

   Example 1.4. Set options_accept_language parameter
...
modparam("siputils", "options_accept_language", "de")
...

3.5. options_support (string)

   This parameter is the content of the Support header field, indicating
   SIP extensions. Please do not change the default value, because
   Kamailio currently does not support any of the SIP extensions
   registered at the IANA.

   Default value is “”.

   Example 1.5. Set options_support parameter
...
modparam("siputils", "options_support", "100rel")
...

3.6. rpid_prefix (string)

   Prefix to be added to Remote-Party-ID header field just before the URI
   returned from either radius or database.

   Default value is “”.

   Example 1.6. rpid_prefix parameter example
modparam("siputils", "rpid_prefix", "Whatever <")

3.7. rpid_suffix (string)

   Suffix to be added to Remote-Party-ID header field after the URI
   returned from either radius or database.

   Default value is “;party=calling;id-type=subscriber;screen=yes”.

   Example 1.7. rpid_suffix parameter example
modparam("siputils", "rpid_suffix", "@1.2.3.4>")

3.8. rpid_avp (string)

   Full AVP specification for the AVP which stores the RPID value. It used
   to transport the RPID value from authentication backend modules
   (auth_db or auth_radius) or from script to the auth function
   append_rpid_hf and is_rpid_user_e164.

   If defined to NULL string, all RPID functions will fail at runtime.

   Default value is “$avp(s:rpid)”.

   Example 1.8. rpid_avp parameter example
modparam("siputils", "rpid_avp", "$avp(myrpid)")

3.9. e164_max_len (int)

   The maximum length for checking e164 numbers, including the leading
   '+'.

   Default value is “16”.

   Example 1.9. e164_max_len parameter example
modparam("siputils", "e164_max_len", 20)

4. Functions

   4.1. options_reply()
   4.2. is_user(username)
   4.3. has_totag()
   4.4. uri_param(param)
   4.5. uri_param(param, value)
   4.6. uri_param_any(param)
   4.7. add_uri_param(param)
   4.8. get_uri_param(name, var)
   4.9. uri_param_rm(param)
   4.10. tel2sip(uri, hostpart, result)
   4.11. tel2sip2(uri, hostpart, result)
   4.12. is_e164(pseudo-variable)
   4.13. is_uri_user_e164(pseudo-variable)
   4.14. is_uri(pseudo-variable)
   4.15. is_tel_number(tval)
   4.16. is_numeric(tval)
   4.17. is_alphanum(tval)
   4.18. is_alphanumex(tval, eset)
   4.19. encode_contact(encoding_prefix, hostpart)
   4.20. decode_contact()
   4.21. decode_contact_header()
   4.22. cmp_uri(str1, str2)
   4.23. cmp_aor(str1, str2)
   4.24. cmp_hdr_name(str1, str2)
   4.25. append_rpid_hf()
   4.26. append_rpid_hf(prefix, suffix)
   4.27. is_rpid_user_e164()
   4.28. set_uri_user(uri, user)
   4.29. set_uri_host(uri, host)
   4.30. is_request()
   4.31. is_reply()
   4.32. is_sip()
   4.33. is_http()
   4.34. is_gruu([uri])
   4.35. is_supported(option)
   4.36. is_first_hop([mode])
   4.37. sip_p_charging_vector(flags)
   4.38. contact_param_encode(pname, saddr)
   4.39. contact_param_encode_alias(pname, saddr)
   4.40. contact_param_decode(pname)
   4.41. contact_param_decode_uri(pname)
   4.42. contact_param_rm(pname)
   4.43. contact_param_check(pname)
   4.44. hdr_date_check(tdiff)
   4.45. sip_parse_headers()

4.1.  options_reply()

   This function checks if the request method is OPTIONS and if the
   request URI does not contain a username. If both are true the request
   will be answered stateless with “200 OK” and the capabilities from the
   modules parameters.

   It sends “500 Server Internal Error” for some errors and returns false
   if it is called for a wrong request.

   The check for the request method and the missing username is optional
   because it is also done by the function itself. But you should not call
   this function outside the myself check because in this case the
   function could answer OPTIONS requests which are sent to you as
   outbound proxy but with another destination than your proxy (this check
   is currently missing in the function).

   This function can be used from REQUEST_ROUTE.

   Example 1.10. options_reply usage
...
if (uri==myself) {
        if ((method==OPTIONS) && (! uri=~"sip:.*[@]+.*")) {
                options_reply();
        }
}
...

4.2.  is_user(username)

   Check if the username in credentials matches the given username.

   Meaning of the parameters is as follows:
     * username - Username string.

   This function can be used from REQUEST_ROUTE.

   Example 1.11. is_user usage
...
if (is_user("john")) {
        ...
};
...

4.3.  has_totag()

   Check if To header field uri contains tag parameter.

   This function can be used from ANY_ROUTE.

   Example 1.12. has_totag usage
...
if (has_totag()) {
        ...
};
...

4.4.  uri_param(param)

   Find if Request URI has a given parameter with no value

   Meaning of the parameters is as follows:
     * param - parameter name to look for.

   This function can be used from REQUEST_ROUTE.

   Example 1.13. uri_param usage
...
if (uri_param("param1")) {
        ...
};
...

4.5.  uri_param(param, value)

   Find if Request URI has a given parameter with matching value

   Meaning of the parameters is as follows:
     * param - parameter name to look for.
     * value - parameter value to match.

   This function can be used from REQUEST_ROUTE.

   Example 1.14. uri_param usage
...
if (uri_param("param1","value1")) {
        ...
};
...

4.6.  uri_param_any(param)

   Find if Request URI has a given parameter with or without value.

   Meaning of the parameters is as follows:
     * param - parameter name to look for.

   This function can be used from REQUEST_ROUTE.

   Example 1.15. uri_param_any usage
...
if (uri_param_any("param1")) {
        ...
}
...

4.7.  add_uri_param(param)

   Add to RURI a parameter (name=value);

   Meaning of the parameters is as follows:
     * param - parameter to be appended in “name=value” format.

   This function can be used from REQUEST_ROUTE.

   Example 1.16. add_uri_param usage
...
add_uri_param("nat=yes");
...

4.8.  get_uri_param(name, var)

   Get the value of RURI parameter.

   Meaning of the parameters is as follows:
     * name - the name of R-URI parameter
     * var - the variable where to store the value of the parameter

   This function can be used from REQUEST_ROUTE.

   Example 1.17. add_uri_param usage
...
get_uri_param("nat", "$var(nat)");
...

4.9.  uri_param_rm(param)

   Remove parameter from Request URI.

   Meaning of the parameters is as follows:
     * param - parameter name.

   This function can be used from REQUEST_ROUTE.

   Example 1.18. uri_param_rm usage
...
if (uri_param_rm("param1")) {
        ...
}
...

4.10.  tel2sip(uri, hostpart, result)

   Converts URI in first param (pseudo variable or string) to SIP URI, if
   it is a tel URI. If conversion was done, writes resulting SIP URI to
   third param (pseudo variable). Returns 1 if conversion succeeded, 2 if
   no conversion was needed, and -1 in case of error.

   The conversion follows the rules in RFC 3261 section 19.1.6:
     * Visual separators ( "-", ".", "(", ")" ) are removed from tel URI
       number before converting it to SIP URI userinfo.
     * tel URI parameters are downcased before appending them to SIP URI
       userinfo

   The SIP URI hostpart is taken from second param (pseudo variable or
   string).

   This function can be used from REQUEST_ROUTE, FAILURE_ROUTE,
   BRANCH_ROUTE, or ONREPLY_ROUTE.

   Example 1.19. tel2sip usage
...
# $ru: tel:+(34)-999-888-777
# $fu: sip:test@foo.com
tel2sip("$ru", $fd", "$ru");
# $ru:  sip:+34999888777@foo.com;user=phone

# $ru: tel:+12-(34)-56-78;Ext=200;ISUB=+123-456
# $fu: sip:test@foo.com
tel2sip("$ru", $fd", "$ru");
# $ru:  sip:+12345678;ext=200;isub=+123-456@foo.com;user=phone
...

4.11.  tel2sip2(uri, hostpart, result)

   Alternative to sip2tel() function that tries to follow closer the RFC
   requrements (e.g., sort tel: uri parameters copied to the sip: uri in
   the manner defined in the standard; deletes the phone-context parameter
   if it is a domain, and, takes visual separators from the phone-context
   parameter if it is a telephone number).

   Its parameters have the same meaning as for tel2sip().

   This function can be used from REQUEST_ROUTE, FAILURE_ROUTE,
   BRANCH_ROUTE, or ONREPLY_ROUTE.

   Example 1.20. tel2sip2 usage
...
# $ru: tel:+(34)-999-888-777
# $fu: sip:test@foo.com
tel2sip2("$ru", $fd", "$ru");
# $ru:  sip:+34999888777@foo.com;user=phone
...

4.12.  is_e164(pseudo-variable)

   Checks if string value of pseudo variable argument is an E164 number.

   This function can be used from REQUEST_ROUTE, FAILURE_ROUTE, and
   LOCAL_ROUTE.

   Example 1.21. is_e164 usage
...
if (is_e164("$fU")) {  # Check From header URI user part
   ...
}
if (is_e164("$avp(i:705)") {
   # Check stgring value stored in avp i:705
   ...
};
...

4.13.  is_uri_user_e164(pseudo-variable)

   Checks if userpart of URI stored in pseudo variable is E164 number.

   This function can be used from ANY_ROUTE.

   Example 1.22. is_uri_user_e164 usage
...
if (is_uri_user_e164("$fu")) {  # Check From header URI user part
   ...
}
if (is_uri_user_e164("$avp(i:705)") {
   # Check user part of URI stored in avp i:705
   ...
};
...

4.14.  is_uri(pseudo-variable)

   Checks if string value of pseudo variable argument is a valid uri.

   This function can be used from ANY_ROUTE.

   Example 1.23. is_uri usage
...
if (is_uri("$var(x)")) {  # Check if variable contains a uri
   ...
}
if (is_uri("$avp(i:705)") {
   # Check value stored in avp i:705
   ...
};
...

4.15.  is_tel_number(tval)

   Checks if the parameter value is a telephone number: starting with one
   optional +, followed by digits. The parameter can include variables.

   This function can be used from ANY_ROUTE.

   Example 1.24. is_tel_number usage
...
if (is_tel_number("$rU")) {  # Test if R-URI user is telephone number
   ...
}
if (is_tel_number("+24242424")) {
   ...
}
...

4.16.  is_numeric(tval)

   Checks if the parameter value consists solely of decimal digits. The
   parameter can include variables.

   This function can be used from ANY_ROUTE.

   Example 1.25. is_numeric usage
...
if (is_numeric("$rU")) {  # Test if R-URI user consists of decimal digits
   ...
}
...

4.17.  is_alphanum(tval)

   Checks if the parameter value consists solely of decimal digits or
   alphabetic ASCII characters. The parameter can include variables.

   This function can be used from ANY_ROUTE.

   Example 1.26. is_alphanum usage
...
if (is_alphanum("$rU")) {
   ...
}
...

4.18.  is_alphanumex(tval, eset)

   Checks if the value of parameter 'tval' consists solely of decimal
   digits, alphabetic ASCII characters and the characters in the second
   parameter 'eset'. The parameters can include variables.

   This function can be used from ANY_ROUTE.

   Example 1.27. is_alphanumex usage
...
if (is_alphanumex("$rU", "+.-_")) {
   ...
}
...

4.19.  encode_contact(encoding_prefix, hostpart)

   This function will encode uri-s inside Contact header in the following
   manner sip:username:password@ip:port;transport=protocol goes
   sip:encoding_prefix*username*password*ip*port*protocol@hostpart.

   * is the default separator and can be changed by setting the
   contact_flds_separator module parameter.

   Note: This function discards all of the URI parameters. Thus, none of
   the parameters (except the transport parameter which is encoded into
   the userpart) can be restored.

   The function returns negative on error, 1 on success.

   Meaning of the parameters is as follows:
     * encoding_prefix - Something to allow us to determine that a contact
       is encoded.
     * hostpart - An IP address or a hostname.

   This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE.

   Example 1.28. encode_contact usage
...
if (src_ip == 10.0.0.0/8) encode_contact("natted_client","1.2.3.4");
...

4.20.  decode_contact()

   This function will decode the request URI. If the RURI is in the format
   sip:encoding_prefix*username*password*ip*port*protocol@hostpart it will
   be decoded to sip:username:password@ip:port;transport=protocol. It uses
   the default set parameter for contact encoding separator.

   The function returns negative on error, 1 on success.

   Meaning of the parameters is as follows:

   This function can be used from REQUEST_ROUTE.

   Example 1.29. decode_contact usage
...
if (uri =~ "^sip:natted_client") { decode_contact(); }
...

4.21.  decode_contact_header()

   This function will decode URIs inside Contact header. If the URI in the
   format sip:encoding_prefix*username*ip*port*protocol@hostpart it will
   be decoded to sip:username:password@ip:port;transport=protocol. It uses
   the default set parameter for contact encoding separator.

   The function returns negative on error, 1 on success.

   Meaning of the parameters is as follows:

   This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE.

   Example 1.30. decode_contact_header usage
...
reply_route[2] {
        ...
        decode_contact_header();
        ...
}
...

4.22.  cmp_uri(str1, str2)

   The function returns true if the two parameters matches as SIP URI.

   This function can be used from ANY_ROUTE.

   Example 1.31. cmp_uri usage
...
if(cmp_uri("$ru", "sip:kamailio@kamailio.org"))
{
    # do interesting stuff here
}
...

4.23.  cmp_aor(str1, str2)

   The function returns true if the two parameters matches as AoR. The
   parameters have to be SIP URIs.

   This function can be used from ANY_ROUTE.

   Example 1.32. cmp_aor usage
...
if(cmp_aor("$rU@KaMaIlIo.org", "sip:kamailio@$fd"))
{
    # do interesting stuff here
}
...

4.24.  cmp_hdr_name(str1, str2)

   The function returns true (return code 1) if the two parameters matches
   as header names.

   This function can be used from ANY_ROUTE.

   Example 1.33. cmp_hdr_name usage
...
if(cmp_hdr_name("$var(hname)", "From"))
{
    # do interesting stuff here
}
...

4.25.  append_rpid_hf()

   Appends to the message a Remote-Party-ID header that contains header
   'Remote-Party-ID: ' followed by the saved value of the SIP URI received
   from the database or radius server followed by the value of module
   parameter radius_rpid_suffix. The function does nothing if no saved SIP
   URI exists.

   This function can be used from REQUEST_ROUTE, FAILURE_ROUTE,
   BRANCH_ROUTE.

   Example 1.34. append_rpid_hf usage
...
append_rpid_hf();  # Append Remote-Party-ID header field
...

4.26.  append_rpid_hf(prefix, suffix)

   This function is the same as Section 4.25, “ append_rpid_hf()”. The
   only difference is that it accepts two parameters--prefix and suffix to
   be added to Remote-Party-ID header field. This function ignores
   rpid_prefix and rpid_suffix parameters, instead of that allows to set
   them in every call.

   Meaning of the parameters is as follows:
     * prefix - Prefix of the Remote-Party-ID URI. The string will be
       added at the beginning of the body of the header field, just before
       the URI.
     * suffix - Suffix of the Remote-Party-ID header field. The string
       will be appended at the end of the header field. It can be used to
       set various URI parameters, for example.

   This function can be used from REQUEST_ROUTE, FAILURE_ROUTE,
   BRANCH_ROUTE.

   Example 1.35. append_rpid_hf(prefix, suffix) usage
...
# Append Remote-Party-ID header field
append_rpid_hf("", ";party=calling;id-type=subscriber;screen=yes");
...

4.27.  is_rpid_user_e164()

   The function checks if the SIP URI received from the database or radius
   server and will potentially be used in Remote-Party-ID header field
   contains an E164 number (+followed by up to 15 decimal digits) in its
   user part. Check fails, if no such SIP URI exists (i.e. radius server
   or database didn't provide this information).

   This function can be used from REQUEST_ROUTE.

   Example 1.36. is_rpid_user_e164 usage
...
if (is_rpid_user_e164()) {
    # do something here
};
...

4.28.  set_uri_user(uri, user)

   Sets userpart of SIP URI stored in writable pseudo variable 'uri' to
   value of pseudo variable 'user'.

   This function can be used from ANY_ROUTE.

   Example 1.37. set_uri_user usage
...
$var(uri) = "sip:user@host";
$var(user) = "new_user";
set_uri_user("$var(uri)", "$var(user)");
...

4.29.  set_uri_host(uri, host)

   Sets hostpart of SIP URI stored in writable pseudo variable 'uri' to
   value of pseudo variable 'host'.

   This function can be used from ANY_ROUTE.

   Example 1.38. set_uri_host usage
...
$var(uri) = "sip:user@host";
$var(host) = "new_host";
set_uri_host("$var(uri)", "$var(host)");
...

4.30.  is_request()

   Return true if the SIP message is a request.

   This function can be used from ANY_ROUTE.

   Example 1.39. is_request usage
...
if (is_request()) {
        ...
}
...

4.31.  is_reply()

   Return true if the SIP message is a reply.

   This function can be used from ANY_ROUTE.

   Example 1.40. is_reply usage
...
if (is_reply()) {
        ...
}
...

4.32.  is_sip()

   Return true if it is a SIP message.

   This function can be used from ANY_ROUTE.

   Example 1.41. is_sip usage
...
if (is_sip()) {
        ...
}
...

4.33.  is_http()

   Return true if it is a HTTP message.

   This function can be used from ANY_ROUTE.

   Example 1.42. is_http usage
...
if (is_http()) {
        ...
}
...

4.34.  is_gruu([uri])

   The function returns true if the uri is GRUU ('gr' parameter is
   present): 1 - pub-gruu; 2 - temp-gruu.

   Meaning of the parameters is as follows:
     * uri - the SIP URI to check for GRUU parameter. It is optional, when
       missing, the value of R-URI is used.

   This function can be used from ANY_ROUTE.

   Example 1.43. is_gruu() usage
...
if(is_gruu()) { ... }
...

4.35.  is_supported(option)

   Function returns true if given option is listed in Supported header(s)
   (if any) of the request. Currently the following options are known:
   path, 100rel, timer, eventlist, gruu, and outbound.

   This function can be used from ANY_ROUTE.

   Example 1.44. is_supported() usage
...
if (is_supported("outbound")) { ... }
...

4.36.  is_first_hop([mode])

   The function returns true if the proxy is first hop after the original
   sender based on a best effort estimation by checking Via and
   Record-Route headers.

   For incoming SIP requests, it means there is only one Via header.

   For incoming SIP replies, if mode==0, it means that top Record-Route
   URI is 'myself' and source address is not matching local IP (to avoid
   detecting in case of local loops). Therefore for mode==0 the detection
   is done only when Record-Route has an IP address in its URI (for a
   domain, it returns -1/false). If mode==1, then the check of local IP is
   no longer done, only if top Record-Route is myself, returning true also
   if there is a domain, assuming that is expected no looping can happen
   based on config rules.

   Note that it does not detect spirals, which can have the condition for
   replies true also in the case of additional SIP reply reception.

   Parameter mode is optional and can be an integer or a variable holding
   an integer. If not provided, the behaviour is like mode==0.

   This function can be used from ANY_ROUTE.

   Example 1.45. is_first_hop() usage
...
if(is_first_hop()) { ... }
...
if(is_first_hop("1")) { ... }
...

4.37.  sip_p_charging_vector(flags)

   Manage the P-Charging-Vector header (RFC7315). The flags can be: 'r' -
   remove; 'g' - generate; 'f' - force (remove + generate). Once a new PCV
   has been generated by 'g' or 'f' the PCV cannot be changed again. The
   icid-generated-at parameter of a generated PCV will be set to the
   sending interface.IP address.

   Return Codes:
     * 1 - Nothing was done.
     * (2 - intentionally left out)
     * 3 - P-Charging-Vector header has been newly generated.
     * 4 - P-Charging-Vector header has been deleted.
     * 5 - P-Charging-Vector header has been replaced or inserted after
       deletion.
     * negative - Any error occured during execution.

   This function can be used from ANY_ROUTE.

   Example 1.46. sip_p_charging_vector() usage
...
sip_p_charging_vector("g");
...

4.38.  contact_param_encode(pname, saddr)

   This function encodes URI inside Contact headers by building a new URI
   from 'saddr' parameter and adding a parameter with the name 'pname'
   containing incoming URI encoded in Base64URL format.

   Meaning of the parameters is as follows:
     * pname - name of the new URI parameter to hold the encoded incoming
       URI.
     * saddr - local server address in SIP URI format.

   This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE.

   Example 1.47. contact_param_encode usage
...
if (is_method("REGISTER") and src_ip == 10.0.0.0/8) {
    contact_param_encode("ksu", "sip:1.2.3.4:5060;transport=tcp");
}
...

4.39.  contact_param_encode_alias(pname, saddr)

   Similar to contact_param_encode() but it also adds the alias parameter
   with the encoded source address to the original Contact URI.

   This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE.

   Example 1.48. contact_param_encode_alias usage
...
if (is_method("SUBSCRIBE") and src_ip == 10.0.0.0/8) {
    contact_param_encode_alias("ksu", "sip:1.2.3.4:5060;transport=tcp");
}
...

4.40.  contact_param_decode(pname)

   This function decodes URI inside Contact headers by building a new URI
   from 'pname' parameter, decoding its value from Base64URL.

   Meaning of the parameters is as follows:
     * pname - name of the incoming URI parameter holding the encoded URI
       value.

   This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE.

   Example 1.49. contact_param_decode usage
...
if (is_method("REGISTER") and src_ip == 1.2.3.4) {
    contact_param_decode("ksu");
}
...

4.41.  contact_param_decode_uri(pname)

   This function decodes R-URI (request URI) by building a new R-URI from
   'pname' parameter, decoding its value from Base64URL.

   Meaning of the parameters is as follows:
     * pname - name of the incoming URI parameter holding the encoded URI
       value.

   This function can be used from REQUEST_ROUTE.

   Example 1.50. contact_param_decode_ruri usage
...
if (is_method("INVITE") and src_ip == 1.2.3.4) {
    contact_param_decode_ruri("ksu");
}
...

4.42.  contact_param_rm(pname)

   This function removes the parameter from the URIs inside the Contact
   headers.

   Meaning of the parameters is as follows:
     * pname - name of the URI parameter.

   This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE.

   Example 1.51. contact_param_rm usage
...
if (is_method("REGISTER") and src_ip == 1.2.3.4) {
    contact_param_rm("myparam");
}
...

4.43.  contact_param_check(pname)

   This function returns true (1) if the URI inside the Contact header
   contains the parameter with the name 'pname'. Otherwise it returns
   false (-1).

   Meaning of the parameters is as follows:
     * pname - name of the URI parameter.

   This function can be used from ANY_ROUTE.

   Example 1.52. contact_param_check usage
...
if (contact_param_check("myparam")) {
}
...

4.44.  hdr_date_check(tdiff)

   Returns true if sip message has Date header and its value is lower than
   'NOW() - tdiff'.

   Meaning of the parameters is as follows:
     * tdiff - time difference in seconds, it can be a variable or static
       integer value.

   This function can be used from ANY_ROUTE.

   Example 1.53. hdr_date_check usage
...
if (!hdr_date_check("10")) {
    sl_send_reply("403", "Outdated date");
    exit;
}
...

4.45.  sip_parse_headers()

   Return true if parsing (fast mode) all SIP headers is successful.

   This function can be used from ANY_ROUTE.

   Example 1.54. sip_parse_headers usage
...
if (sip_parse_headers()) {
        ...
}
...

5. Exported pseudo-variables

   5.1. $pcv(all)
   5.2. $pcv(value)
   5.3. $pcv(genaddr)
   5.4. $pcv(orig)
   5.5. $pcv(term)
   5.6. $pcv(status)

5.1. $pcv(all)

   full P-Charging-Vector header

5.2. $pcv(value)

   icid-value field (see RFC7315 section 5.6)

5.3. $pcv(genaddr)

   icid-generated-at field (see RFC7315 section 5.6)

5.4. $pcv(orig)

   orig-ioi field (see RFC7315 section 5.6)

5.5. $pcv(term)

   term-ioi field (see RFC7315 section 5.6)

5.6. $pcv(status)

   Returns whether the PCV header was successfully parsed, deleted, newly
   generated or other.
     * 0 - No P-Charging-Vector header in message.
     * 1 - P-Charging-Vector header in message and parsed successfully.
     * 2 - P-Charging-Vector is present, but has no valid icid-value
       parameter.
     * 3 - P-Charging-Vector header has been newly generated or replaced.
     * 4 - P-Charging-Vector header has been deleted.

   Negative values indicate an internal error during the parsing process.
