textops Module

Andrei Pelinescu-Onciul

   FhG FOKUS
   <pelinescu-onciul@fokus.fraunhofer.de>

Edited by

Andrei Pelinescu-Onciul

   <pelinescu-onciul@fokus.fraunhofer.de>

Daniel-Constantin Mierla

   <miconda@gmail.com>

Juha Heinanen

   <jh@tutpro.com>

Ovidiu Sas

   <osas@voipembedded.com>

   Copyright © 2003 FhG FOKUS
     __________________________________________________________________

   Table of Contents

   1. Admin Guide

        1. Overview
        2. Known Limitations
        3. Dependencies

              3.1. Kamailio Modules
              3.2. External Libraries or Applications

        4. Functions

              4.1. search(re)
              4.2. search_body(re)
              4.3. search_str(text, re)
              4.4. search_hf(hf, re, flags)
              4.5. search_append(re, txt)
              4.6. search_append_body(re, txt)
              4.7. replace(re, txt)
              4.8. replace_body(re, txt)
              4.9. replace_hdrs(re, txt)
              4.10. replace_all(re, txt)
              4.11. replace_body_all(re, txt)
              4.12. replace_body_atonce(re, txt)
              4.13. replace_str(match, repl, mode)
              4.14. replace_body_str(match, repl, mode)
              4.15. replace_hdrs_str(match, repl, mode)
              4.16. subst('/re/repl/flags')
              4.17. subst_uri('/re/repl/flags')
              4.18. subst_user('/re/repl/flags')
              4.19. subst_body('/re/repl/flags')
              4.20. subst_hf(hf, subexp, flags)
              4.21. set_body(txt, content_type)
              4.22. set_reply_body(txt, content_type)
              4.23. filter_body(content_type)
              4.24. append_to_reply(txt)
              4.25. append_hf(txt[, hdr])
              4.26. insert_hf(txt[, hdr])
              4.27. append_urihf(prefix, suffix)
              4.28. is_present_hf(hf_name)
              4.29. is_present_hf_pv(hf_name)
              4.30. is_present_hf_re(hf_name_re)
              4.31. is_present_hf_re_pv(hf_name_re)
              4.32. append_time()
              4.33. append_time_to_request()
              4.34. is_method(name)
              4.35. remove_hf(hname)
              4.36. remove_hf_pv(hname)
              4.37. remove_hf_re(re)
              4.38. remove_hf_re_pv(re)
              4.39. remove_hf_exp(expmatch, expskip)
              4.40. remove_hf_exp_pv(expmatch, expskip)
              4.41. remove_hf_idx(hname, idx)
              4.42. remove_hf_match(hname, op, expr)
              4.43. has_body(), has_body(mime)
              4.44. is_audio_on_hold()
              4.45. is_privacy(privacy_type)
              4.46. in_list(subject, list, separator)
              4.47. in_list_prefix(subject, list, separator)
              4.48. cmp_str(str1, str2)
              4.49. cmp_istr(str1, str2)
              4.50. starts_with(str1, str2)
              4.51. ends_with(str1, str2)
              4.52. str_find(str1, str2)
              4.53. str_ifind(str1, str2)
              4.54. str_any_in(txt, clist)
              4.55. set_body_multipart([txt, content_type][, boundary])
              4.56. append_body_part(txt, content_type[,
                      content_disposition])

              4.57. append_body_part_hex(txt, content_type[,
                      content_disposition])

              4.58. get_body_part(content_type, opv)
              4.59. get_body_part_raw(content_type, opv)
              4.60. remove_body_part(content_type)
              4.61. regex_substring(itext, regexp, mindex, mcount, dpv)

   2. Developer Guide

        1. Functions

              1.1. load_textops(*import_structure)

   List of Examples

   1.1. search usage
   1.2. search_body usage
   1.3. search_str usage
   1.4. search_hf usage
   1.5. search_append usage
   1.6. search_append_body usage
   1.7. replace usage
   1.8. replace_body usage
   1.9. replace_hdrs usage
   1.10. replace_all usage
   1.11. replace_body_all usage
   1.12. replace_body_atonce usage
   1.13. replace_str usage
   1.14. replace_body_str usage
   1.15. replace_hdrs_str usage
   1.16. subst usage
   1.17. subst_uri usage
   1.18. subst usage
   1.19. subst_body usage
   1.20. subst_hf usage
   1.21. set_body usage
   1.22. set_reply_body usage
   1.23. filter_body usage
   1.24. append_to_reply usage
   1.25. append_hf usage
   1.26. insert_hf usage
   1.27. append_urihf usage
   1.28. is_present_hf usage
   1.29. is_present_hf_pv usage
   1.30. is_present_hf_re usage
   1.31. is_present_hf_re_pv usage
   1.32. append_time usage
   1.33. append_time_to_request usage
   1.34. is_method usage
   1.35. remove_hf usage
   1.36. remove_hf_pv usage
   1.37. remove_hf_re usage
   1.38. remove_hf_re_pv usage
   1.39. remove_hf_exp usage
   1.40. remove_hf_exp_pv usage
   1.41. remove_hf_idx usage
   1.42. remove_hf_match usage
   1.43. has_body usage
   1.44. is_audio_on_hold usage
   1.45. is_privacy usage
   1.46. in_list usage
   1.47. in_list_prefix usage
   1.48. cmp_str usage
   1.49. cmp_str usage
   1.50. starts_with usage
   1.51. ends_with usage
   1.52. str_find usage
   1.53. str_ifind usage
   1.54. str_any_in usage
   1.55. set_body_multipart usage
   1.56. append_body_part usage
   1.57. append_body_part with headers
   1.58. append_body_part_hex usage
   1.59. get_body_part usage
   1.60. get_body_part_raw usage
   1.61. remove_body_part usage
   1.62. _regex_substring usage

Chapter 1. Admin Guide

   Table of Contents

   1. Overview
   2. Known Limitations
   3. Dependencies

        3.1. Kamailio Modules
        3.2. External Libraries or Applications

   4. Functions

        4.1. search(re)
        4.2. search_body(re)
        4.3. search_str(text, re)
        4.4. search_hf(hf, re, flags)
        4.5. search_append(re, txt)
        4.6. search_append_body(re, txt)
        4.7. replace(re, txt)
        4.8. replace_body(re, txt)
        4.9. replace_hdrs(re, txt)
        4.10. replace_all(re, txt)
        4.11. replace_body_all(re, txt)
        4.12. replace_body_atonce(re, txt)
        4.13. replace_str(match, repl, mode)
        4.14. replace_body_str(match, repl, mode)
        4.15. replace_hdrs_str(match, repl, mode)
        4.16. subst('/re/repl/flags')
        4.17. subst_uri('/re/repl/flags')
        4.18. subst_user('/re/repl/flags')
        4.19. subst_body('/re/repl/flags')
        4.20. subst_hf(hf, subexp, flags)
        4.21. set_body(txt, content_type)
        4.22. set_reply_body(txt, content_type)
        4.23. filter_body(content_type)
        4.24. append_to_reply(txt)
        4.25. append_hf(txt[, hdr])
        4.26. insert_hf(txt[, hdr])
        4.27. append_urihf(prefix, suffix)
        4.28. is_present_hf(hf_name)
        4.29. is_present_hf_pv(hf_name)
        4.30. is_present_hf_re(hf_name_re)
        4.31. is_present_hf_re_pv(hf_name_re)
        4.32. append_time()
        4.33. append_time_to_request()
        4.34. is_method(name)
        4.35. remove_hf(hname)
        4.36. remove_hf_pv(hname)
        4.37. remove_hf_re(re)
        4.38. remove_hf_re_pv(re)
        4.39. remove_hf_exp(expmatch, expskip)
        4.40. remove_hf_exp_pv(expmatch, expskip)
        4.41. remove_hf_idx(hname, idx)
        4.42. remove_hf_match(hname, op, expr)
        4.43. has_body(), has_body(mime)
        4.44. is_audio_on_hold()
        4.45. is_privacy(privacy_type)
        4.46. in_list(subject, list, separator)
        4.47. in_list_prefix(subject, list, separator)
        4.48. cmp_str(str1, str2)
        4.49. cmp_istr(str1, str2)
        4.50. starts_with(str1, str2)
        4.51. ends_with(str1, str2)
        4.52. str_find(str1, str2)
        4.53. str_ifind(str1, str2)
        4.54. str_any_in(txt, clist)
        4.55. set_body_multipart([txt, content_type][, boundary])
        4.56. append_body_part(txt, content_type[, content_disposition])
        4.57. append_body_part_hex(txt, content_type[,
                content_disposition])

        4.58. get_body_part(content_type, opv)
        4.59. get_body_part_raw(content_type, opv)
        4.60. remove_body_part(content_type)
        4.61. regex_substring(itext, regexp, mindex, mcount, dpv)

1. Overview

   The module implements text based operations over the SIP message
   processed by Kamailio. SIP is a text based protocol and the module
   provides a large set of very useful functions to manipulate the message
   at text level, e.g., regular expression search, replace or
   substitutions, checks for method type, header presence, insert of new
   header and date, string comparisons, multi-part body operations, etc.

   If not stated otherwise, the regular expressions parameters for search,
   replace or substitute have to be in POSIX format. For PCRE regular
   expression matching, see the pcre or dialplan modules.

2. Known Limitations

   Search functions are applied to the original request, i.e., they ignore
   all changes resulting from message processing in Kamailio script.

   Search ignores folded lines. For example, search(“(From|f):.*@foo.bar”)
   doesn't match the following From header field:
From: medabeda
 <sip:medameda@foo.bar>;tag=1234

3. Dependencies

   3.1. Kamailio Modules
   3.2. External Libraries or Applications

3.1. Kamailio Modules

   The following modules must be loaded before this module:
     * No dependencies on other Kamailio modules.

3.2. External Libraries or Applications

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

4. Functions

   4.1. search(re)
   4.2. search_body(re)
   4.3. search_str(text, re)
   4.4. search_hf(hf, re, flags)
   4.5. search_append(re, txt)
   4.6. search_append_body(re, txt)
   4.7. replace(re, txt)
   4.8. replace_body(re, txt)
   4.9. replace_hdrs(re, txt)
   4.10. replace_all(re, txt)
   4.11. replace_body_all(re, txt)
   4.12. replace_body_atonce(re, txt)
   4.13. replace_str(match, repl, mode)
   4.14. replace_body_str(match, repl, mode)
   4.15. replace_hdrs_str(match, repl, mode)
   4.16. subst('/re/repl/flags')
   4.17. subst_uri('/re/repl/flags')
   4.18. subst_user('/re/repl/flags')
   4.19. subst_body('/re/repl/flags')
   4.20. subst_hf(hf, subexp, flags)
   4.21. set_body(txt, content_type)
   4.22. set_reply_body(txt, content_type)
   4.23. filter_body(content_type)
   4.24. append_to_reply(txt)
   4.25. append_hf(txt[, hdr])
   4.26. insert_hf(txt[, hdr])
   4.27. append_urihf(prefix, suffix)
   4.28. is_present_hf(hf_name)
   4.29. is_present_hf_pv(hf_name)
   4.30. is_present_hf_re(hf_name_re)
   4.31. is_present_hf_re_pv(hf_name_re)
   4.32. append_time()
   4.33. append_time_to_request()
   4.34. is_method(name)
   4.35. remove_hf(hname)
   4.36. remove_hf_pv(hname)
   4.37. remove_hf_re(re)
   4.38. remove_hf_re_pv(re)
   4.39. remove_hf_exp(expmatch, expskip)
   4.40. remove_hf_exp_pv(expmatch, expskip)
   4.41. remove_hf_idx(hname, idx)
   4.42. remove_hf_match(hname, op, expr)
   4.43. has_body(), has_body(mime)
   4.44. is_audio_on_hold()
   4.45. is_privacy(privacy_type)
   4.46. in_list(subject, list, separator)
   4.47. in_list_prefix(subject, list, separator)
   4.48. cmp_str(str1, str2)
   4.49. cmp_istr(str1, str2)
   4.50. starts_with(str1, str2)
   4.51. ends_with(str1, str2)
   4.52. str_find(str1, str2)
   4.53. str_ifind(str1, str2)
   4.54. str_any_in(txt, clist)
   4.55. set_body_multipart([txt, content_type][, boundary])
   4.56. append_body_part(txt, content_type[, content_disposition])
   4.57. append_body_part_hex(txt, content_type[, content_disposition])
   4.58. get_body_part(content_type, opv)
   4.59. get_body_part_raw(content_type, opv)
   4.60. remove_body_part(content_type)
   4.61. regex_substring(itext, regexp, mindex, mcount, dpv)

4.1.  search(re)

   Searches for the re in the message.

   Meaning of the parameters is as follows:
     * re - Regular expression.

   Note: it performs Posix regex matching and the 're' parameter is
   compiled with the flags REG_EXTENDED|REG_ICASE|REG_NEWLINE.

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

   Example 1.1. search usage
...
if ( search("[Ss][Ii][Pp]") ) { /*....*/ };
...

4.2.  search_body(re)

   Searches for the re in the body of the message.

   Meaning of the parameters is as follows:
     * re - Regular expression.

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

   Example 1.2. search_body usage
...
if ( search_body("[Ss][Ii][Pp]") ) { /*....*/ };
...

4.3.  search_str(text, re)

   Searches for the re in the body of the message.

   Meaning of the parameters is as follows:
     * text - text to perform regex searching over it.
     * re - regular expression to match over the 'text' parameter.

   Both parameters can contain variables.

   This function can be used from ANY_ROUTE.

   Example 1.3. search_str usage
...
if ( search_str("$ru", ";transport=tcp") ) { /*....*/ };
...

4.4.  search_hf(hf, re, flags)

   Searches for the re in the body of a header field.

   Meaning of the parameters is as follows:
     * hf - header field name.
     * re - regular expression.
     * flags - control flags - it has to be one of: a - all headers
       matching the name; f - only first header matching the name; l -
       only the last header matching the name.

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

   Example 1.4. search_hf usage
...
if ( search_hf("From", ":test@", "a") ) { /*....*/ };
...

4.5.  search_append(re, txt)

   Searches for the first match of re and appends txt after it.

   Meaning of the parameters is as follows:
     * re - Regular expression.
     * txt - String to be appended.

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

   Example 1.5. search_append usage
...
search_append("[Oo]pen[Ss]er", " SIP Proxy");
...

4.6.  search_append_body(re, txt)

   Searches for the first match of re in the body of the message and
   appends txt after it.

   Meaning of the parameters is as follows:
     * re - Regular expression.
     * txt - String to be appended.

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

   Example 1.6. search_append_body usage
...
search_append_body("[Oo]pen[Ss]er", " SIP Proxy");
...

4.7.  replace(re, txt)

   Replaces the first occurrence of re with txt.

   Meaning of the parameters is as follows:
     * re - Regular expression.
     * txt - String.

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

   Example 1.7. replace usage
...
replace("server", "Kamailio SIP Proxy");
...

4.8.  replace_body(re, txt)

   Replaces the first occurrence of re in the body of the message with
   txt.

   Meaning of the parameters is as follows:
     * re - Regular expression.
     * txt - String.

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

   Example 1.8. replace_body usage
...
replace_body("server", "Kamailio SIP Proxy");
...

4.9.  replace_hdrs(re, txt)

   Replaces the first occurrence of re in the SIP headers of the message
   with txt.

   Meaning of the parameters is as follows:
     * re - Regular expression.
     * txt - String.

   This function can be used from ANY_ROUTE.

   Example 1.9. replace_hdrs usage
...
replace_hdrs("Kamailio", "Kamailio SIP Proxy");
...

4.10.  replace_all(re, txt)

   Replaces all occurrence of re with txt.

   Meaning of the parameters is as follows:
     * re - Regular expression.
     * txt - String.

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

   Example 1.10. replace_all usage
...
replace_all("server", "Kamailio SIP Proxy");
...

4.11.  replace_body_all(re, txt)

   Replaces all occurrence of re in the body of the message with txt.
   Matching is done on a per-line basis.

   Meaning of the parameters is as follows:
     * re - Regular expression.
     * txt - String.

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

   Example 1.11. replace_body_all usage
...
replace_body_all("server", "Kamailio SIP Proxy");
...

4.12.  replace_body_atonce(re, txt)

   Replaces all occurrence of re in the body of the message with txt.
   Matching is done over the whole body.

   Meaning of the parameters is as follows:
     * re - Regular expression.
     * txt - String.

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

   Example 1.12. replace_body_atonce usage
...
# strip the whole body from the message:
if(has_body() && replace_body_atonce("^.+$", ""))
        remove_hf("Content-Type");
...

4.13.  replace_str(match, repl, mode)

   Replaces the first or all occurrence of 'match' with 'repl' by doing
   string comparison for matching. It is applied over headers and message
   body (not over the first line).

   Meaning of the parameters is as follows:
     * match - string to be matched.
     * repl - string to be used as replacement.
     * mode - 'f' - replace only first match; 'a' - replace all matches.

   This function can be used from ANY_ROUTE.

   Example 1.13. replace_str usage
...
replace_str("Kamailio", "Kamailio SIP Proxy", "a");
...

4.14.  replace_body_str(match, repl, mode)

   Replaces the first or all occurrence of 'match' with 'repl' by doing
   string comparison for matching. It is applied over the message body.

   Meaning of the parameters is as follows:
     * match - string to be matched.
     * repl - string to be used as replacement.
     * mode - 'f' - replace only first match; 'a' - replace all matches.

   This function can be used from ANY_ROUTE.

   Example 1.14. replace_body_str usage
...
replace_body_str("Kamailio", "Kamailio SIP Proxy", "a");
...

4.15.  replace_hdrs_str(match, repl, mode)

   Replaces the first or all occurrence of 'match' with 'repl' by doing
   string comparison for matching. It is applied over the part with
   headers of the SIP message.

   Meaning of the parameters is as follows:
     * match - string to be matched.
     * repl - string to be used as replacement.
     * mode - 'f' - replace only first match; 'a' - replace all matches.

   This function can be used from ANY_ROUTE.

   Example 1.15. replace_hdrs_str usage
...
replace_hdrs_str("Kamailio", "Kamailio SIP Proxy", "a");
...

4.16.  subst('/re/repl/flags')

   Replaces re with repl.

   Meaning of the parameters is as follows:
     * '/re/repl/flags' - sed like regular expression. flags can be a
       combination of i (case insensitive), g (global) or s (match newline
       don't treat it as end of line).
       're' - is regular expression
       'repl' - is replacement string - may contain pseudo-variables
       'flags' - substitution flags (i - ignore case, g - global)

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

   Example 1.16. subst usage
...
# replace the uri in to: with the message uri (just an example)
if ( subst('/^To:(.*)sip:[^@]*@[a-zA-Z0-9.]+(.*)$/t:\1\u\2/ig') ) {};

# replace the uri in to: with the value of avp sip_address (just an example)
if ( subst('/^To:(.*)sip:[^@]*@[a-zA-Z0-9.]+(.*)$/t:\1$avp(sip_address)\2/ig') )
 {};

...

4.17.  subst_uri('/re/repl/flags')

   Runs the re substitution on the message uri (like subst but works only
   on the uri)

   Meaning of the parameters is as follows:
     * '/re/repl/flags' - sed like regular expression. flags can be a
       combination of i (case insensitive), g (global) or s (match newline
       don't treat it as end of line).
       're' - is regular expression
       'repl' - is replacement string - may contain pseudo-variables
       'flags' - substitution flags (i - ignore case, g - global)

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

   Example 1.17. subst_uri usage
...
# adds 3463 prefix to numeric uris, and save the original uri (\0 match)
# as a parameter: orig_uri (just an example)
if (subst_uri('/^sip:([0-9]+)@(.*)$/sip:3463\1@\2;orig_uri=\0/i')){$

# adds the avp 'uri_prefix' as prefix to numeric uris, and save the original
# uri (\0 match) as a parameter: orig_uri (just an example)
if (subst_uri('/^sip:([0-9]+)@(.*)$/sip:$avp(uri_prefix)\1@\2;orig_uri=\0/i')){$

...

4.18.  subst_user('/re/repl/flags')

   Runs the re substitution on the message uri (like subst_uri but works
   only on the user portion of the uri)

   Meaning of the parameters is as follows:
     * '/re/repl/flags' - sed like regular expression. flags can be a
       combination of i (case insensitive), g (global) or s (match newline
       don't treat it as end of line).
       're' - is regular expression
       'repl' - is replacement string - may contain pseudo-variables
       'flags' - substitution flags (i - ignore case, g - global)

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

   Example 1.18. subst usage
...
# adds 3463 prefix to uris ending with 3642 (just an example)
if (subst_user('/3642$/36423463/')){$

...
# adds avp 'user_prefix' as prefix to username in r-uri ending with 3642
if (subst_user('/(.*)3642$/$avp(user_prefix)\13642/')){$

...

4.19.  subst_body('/re/repl/flags')

   Replaces re with repl in the body of the message.

   Meaning of the parameters is as follows:
     * '/re/repl/flags' - sed like regular expression. flags can be a
       combination of i (case insensitive), g (global) or s (match newline
       don't treat it as end of line).
       're' - is regular expression
       'repl' - is replacement string - may contain pseudo-variables
       'flags' - substitution flags (i - ignore case, g - global)

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

   Example 1.19. subst_body usage
...
if ( subst_body('/^o=(.*) /o=$fU /') ) {};

...

4.20.  subst_hf(hf, subexp, flags)

   Substitutions in the body of a header field.

   Meaning of the parameters is as follows:
     * hf - header field name.
     * subexp - substitution expression in the same format as of the
       'subst' function parameter.
     * flags - control flags - it has to be one of: a - all headers
       matching the name; f - only first header matching the name; l -
       only the last header matching the name.

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

   Example 1.20. subst_hf usage
...
if ( subst_hf("From", "/:test@/:best@/", "a") ) { /*....*/ };
...

4.21.  set_body(txt, content_type)

   Set body to a SIP message.

   Meaning of the parameters is as follows:
     * txt - text for the body, can include pseudo-variables.
     * content_type - value of Content-Type header, can include
       pseudo-variables.

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

   Example 1.21. set_body usage
...
set_body("test", "text/plain");
...

4.22.  set_reply_body(txt, content_type)

   Set body to a SIP reply to be generated by Kamailio.

   Meaning of the parameters is as follows:
     * txt - text for the body, can include pseudo-variables.
     * content_type - value of Content-Type header, can include
       pseudo-variables.

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

   Example 1.22. set_reply_body usage
...
set_reply_body("test", "text/plain");
...

4.23.  filter_body(content_type)

   Filters multipart/mixed body by leaving out all other body parts except
   the first body part of given type.

   Meaning of the parameters is as follows:
     * content_type - Content type to be left in the body.

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

   Example 1.23. filter_body usage
...
if (has_body("multipart/mixed")) {
    if (filter_body("application/sdp")) {
        remove_hf("Content-Type");
        append_hf("Content-Type: application/sdp\r\n");
    } else {
        xlog("Body part application/sdp not found\n");
    }
}
...

4.24.  append_to_reply(txt)

   Append txt as header to the reply that is going to be generated by
   Kamailio (e.g., via sl_send_reply(...)).

   Meaning of the parameters is as follows:
     * txt - String which may contains pseudo-variables. Note that the
       value has to be ended with "\r\n" (end of header characters
       sequence).

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

   Example 1.24. append_to_reply usage
...
append_to_reply("Foo: bar\r\n");
append_to_reply("Foo: $rm at $Ts\r\n");
...

4.25.  append_hf(txt[, hdr])

   Appends 'txt' as header at the end of all the headers, or after last
   header named 'hdr' if the second parameter is provided.

   Meaning of the parameters is as follows:
     * txt - Header field to be appended. The value can contain
       pseudo-variables which will be replaced at run time. Note that the
       value has to be ended with "\r\n" (end of header characters
       sequence).
     * hdr - Header name after which the 'txt' is appended.

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

   Example 1.25. append_hf usage
...
append_hf("P-hint: VOICEMAIL\r\n");
append_hf("From-username: $fU\r\n", "Call-ID");
...

4.26.  insert_hf(txt[, hdr])

   Inserts 'txt' as header before the first header field, or before first
   header named 'hdr' if the second parameter is provided.

   Meaning of the parameters is as follows:
     * txt - Header field to be inserted. The value can contain
       pseudo-variables which will be replaced at run time. Note that the
       value has to be ended with "\r\n" (end of header characters
       sequence).
     * hdr - Header name before which the 'txt' is inserted.

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

   Example 1.26. insert_hf usage
...
insert_hf("P-hint: VOICEMAIL\r\n");
insert_hf("To-username: $tU\r\n");
insert_hf("P-hint: VOICEMAIL\r\n", "Call-ID");
insert_hf("To-username: $tU\r\n", "Call-ID");
...

4.27.  append_urihf(prefix, suffix)

   Append header field name with original Request-URI in middle.

   Meaning of the parameters is as follows:
     * prefix - string (usually at least header field name).
     * suffix - string (usually at least line terminator).

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

   Example 1.27. append_urihf usage
...
append_urihf("CC-Diversion: ", "\r\n");
...

4.28.  is_present_hf(hf_name)

   Return true if a header field is present in message.

Note

   The function is also able to distinguish the compact names. For exmaple
   “From” will match with “f”

   Meaning of the parameters is as follows:
     * hf_name - Header field name (long or compact form). It can be only
       a static string value.

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

   Example 1.28. is_present_hf usage
...
if (is_present_hf("From")) xlog("From HF Present");
...

4.29.  is_present_hf_pv(hf_name)

   Same as is_present_hf() function, but the parameter can contain
   variables.

   Example 1.29. is_present_hf_pv usage
...
if (is_present_hf_pv("$var(hname)")) xinfo("Header $var(hname) is present\n");
...

4.30.  is_present_hf_re(hf_name_re)

   Return true if a header field whose name matches regular expression
   'hf_name_re' is present in message.

   Meaning of the parameters is as follows:
     * hf_name_re - Regular expression to match header field name. It can
       be only a static string value.

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

   Example 1.30. is_present_hf_re usage
...
if (is_present_hf_re("^P-"))
    xlog("There are headers starting with P-\n");
...

4.31.  is_present_hf_re_pv(hf_name_re)

   Same as is_present_hf_re() function, but the parameter can contain
   variables.

   Example 1.31. is_present_hf_re_pv usage
...
if (is_present_hf_re_pv_("^$var(prefix)"))
    xlog("There are headers starting with $var(prefix)\n");
...

4.32.  append_time()

   Adds a time header to the reply of the request. You must use it before
   functions that are likely to send a reply, e.g., save() from
   'registrar' module. Header format is: “Date: %a, %d %b %Y %H:%M:%S
   GMT”, with the legend:
     * %a abbreviated week of day name (locale)
     * %d day of month as decimal number
     * %b abbreviated month name (locale)
     * %Y year with century
     * %H hour
     * %M minutes
     * %S seconds

   Return true if a header was successfully appended.

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

   Example 1.32. append_time usage
...
append_time();
...

4.33.  append_time_to_request()

   Adds a time header to the request. Header format is: “Date: %a, %d %b
   %Y %H:%M:%S GMT”, with the legend:
     * %a abbreviated week of day name (locale)
     * %d day of month as decimal number
     * %b abbreviated month name (locale)
     * %Y year with century
     * %H hour
     * %M minutes
     * %S seconds

   Return true if a header was successfully appended.

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

   Example 1.33. append_time_to_request usage
...
if(!is_present_hf("Date"))
    append_time_to_request();
...

4.34.  is_method(name)

   Check if the method of the message matches the name. If name is a known
   method (invite, cancel, ack, bye, options, info, update, register,
   message, subscribe, notify, refer, prack), the function performs method
   ID testing (integer comparison) instead of ignore case string
   comparison.

   The 'name' can be a list of methods in the form of
   'method1|method2|...'. In this case, the function returns true if the
   SIP message's method is one from the list. IMPORTANT NOTE: in the list
   must be only methods defined in Kamailio with ID (invite, cancel, ack,
   bye, options, info, update, register, message, subscribe, notify,
   refer, prack, publish; for more see:
   http://www.iana.org/assignments/sip-parameters).

   If used for replies, the function tests the value of method field from
   CSeq header.

   Meaning of the parameters is as follows:
     * name - SIP method name

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

   Example 1.34. is_method usage
...
if(is_method("INVITE"))
{
    # process INVITEs here
}
if(is_method("OPTION|UPDATE"))
{
    # process OPTIONs and UPDATEs here
}
...

4.35.  remove_hf(hname)

   Remove from message all headers with name “hname”. Header matching is
   case-insensitive. Matches and removes also the compact header forms.

   Returns true if at least one header is found and removed.

   Meaning of the parameters is as follows:
     * hname - header name to be removed. It can be only a static string
       (because of the optimizations done at startup to speed up execution
       at runtime).

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

   Example 1.35. remove_hf usage
...
if(remove_hf("User-Agent"))
{
    # User Agent header removed
}
# compact form: remove "Contact" or "m" header
remove_hf("Contact");
# compact form: remove "Contact" or "m" header
remove_hf("m");
...

4.36.  remove_hf_pv(hname)

   Same as remove_hf() function, but the parameter can contain variables.

   Example 1.36. remove_hf_pv usage
...
remove_hf_pv("$var(hname)");
...

4.37.  remove_hf_re(re)

   Remove from message all headers with name matching regular expression
   “re”

   Returns true if at least one header is found and removed.

   Meaning of the parameters is as follows:
     * re - regular expression to match the header name to be removed.

   This function can be used from ANY_ROUTE.

   Example 1.37. remove_hf_re usage
...
if(remove_hf_re("^P-"))
{
    # All headers starting with "P-" removed
}
...

4.38.  remove_hf_re_pv(re)

   Same as remove_hf_re() function, but the parameter can contain
   variables.

   Example 1.38. remove_hf_re_pv usage
...
if(remove_hf_re_pv("^$var(prefix)"))
{
    # All headers starting with $var(prefix) value removed
}
...

4.39.  remove_hf_exp(expmatch, expskip)

   Remove from message all headers with name matching regular expression
   “expmatch”, but not matching regular expression “expskip”.

   Returns true if at least one header is found and removed.

   Meaning of the parameters is as follows:
     * expmatch - regular expression to match the header name to be
       removed.
     * expskip - regular expression to match the header name to be skipped
       from removal.

   This function can be used from ANY_ROUTE.

   Example 1.39. remove_hf_exp usage
...
if(remove_hf_exp("^P-", "^P-Keep-"))
{
    # All headers starting with "P-" removed,
    # except the ones starting with "P-Keep-"
}
...

4.40.  remove_hf_exp_pv(expmatch, expskip)

   Same as remove_hf_exp() function, but the parameters can contain
   variables.

   Example 1.40. remove_hf_exp_pv usage
...
if(remove_hf_exp_pv("^$var(match)", "^$var(keep)"))
{
    # All headers starting with $var(match) value removed,
    # except the ones starting with $var(keep) value
}
...

4.41.  remove_hf_idx(hname, idx)

   Remove from message the headers matching by name 'hname' with the index
   'idx'.

   Returns true if the header is removed.

   Meaning of the parameters is as follows:
     * hname - header name.
     * idx - index of the header, starting from 0 with first header;
       negative values count from the end of the headers, -1 being the
       last header matching the name.

   The parameters can be config variables.

   This function can be used from ANY_ROUTE.

   Example 1.41. remove_hf_idx usage
...
remove_hf_idx("X-My-Header", "-1");
...

4.42.  remove_hf_match(hname, op, expr)

   Remove from message all headers with name 'hname' matching the body
   with expression “expr”, based on operator “op”.

   Returns true if at least one header is found and removed.

   Meaning of the parameters is as follows:
     * hanem - name of the header.
     * op - operator - it can be: 'eq' - equal; 'ne' - not equal; 'in' -
       include; 're' - regular expression match.
     * expr - expression to match.

   This function can be used from ANY_ROUTE.

   Example 1.42. remove_hf_match usage
...
if(remove_hf_match("X-Info", "in", "^data")) {
    # all headers with name "X-Info" that have the body matching regular
    # expression "^data" are removed
}
...

4.43.  has_body(), has_body(mime)

   The function returns true if the SIP message has a body attached. The
   check includes also the “Content-Length” header presence and value.

   If a parameter is given, the mime described will be also checked
   against the “Content-Type” header.

   Meaning of the parameters is as follows:
     * mime - mime to be checked against the “Content-Type” header. If not
       present or 0, this check will be disabled.

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

   Example 1.43. has_body usage
...
if(has_body("application/sdp"))
{
    # do interesting stuff here
}
...

4.44.  is_audio_on_hold()

   The function returns true if the SIP message has a body attached and at
   least one audio stream in on hold. The return code of the function
   indicates the detected hold type:
     * 1 - RFC2543 hold type: null connection IP detected
     * 2 - RFC3264 hold type: inactive or sendonly attributes detected

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

   Example 1.44. is_audio_on_hold usage
...
if(is_audio_on_hold())
{
    switch ($rc) {
    case 1:
        # RFC2543 hold type
        # do interesting stuff here
        break;
    case 2:
        # RFC3264 hold type
        # do interesting stuff here
        break;
}
...

4.45.  is_privacy(privacy_type)

   The function returns true if the SIP message has a Privacy header field
   that includes the given privacy_type among its privacy values. See
   http://www.iana.org/assignments/sip-priv-values for possible privacy
   type values.

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

   Example 1.45. is_privacy usage
...
if(is_privacy("id"))
{
    # do interesting stuff here
}
...

4.46.  in_list(subject, list, separator)

   Function checks if subject string is found in list string where list
   items are separated by separator string. Subject and list strings may
   contain pseudo variables. Separator string needs to be one character
   long. Returns 1 if subject is found and -1 otherwise.

   Function can be used from all kinds of routes.

   Example 1.46. in_list usage
...
$var(subject) = "fi";
$var(list) = "dk,fi,no,se";
if (in_list("$var(subject)", "$var(list)", ",")) {
    xlog("L_INFO", "subject is found in list\n");
}
...

4.47.  in_list_prefix(subject, list, separator)

   Function checks if any element in list string is a prefix for subject
   string where list items are separated by separator string. Subject and
   list strings may contain pseudo variables. Separator string needs to be
   one character long. Returns 1 if subject is found and -1 otherwise.

   Function can be used from all kinds of routes.

   Example 1.47. in_list_prefix usage
...
$var(subject) = "final";
$var(list) = "dk,fi,no,se";
if (in_list_prefix("$var(subject)", "$var(list)", ",")) {
    xlog("L_INFO", "prefix for subject is found in list\n");
}
...

4.48.  cmp_str(str1, str2)

   The function returns true if the two parameters matches as string case
   sensitive comparison.

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

   Example 1.48. cmp_str usage
...
if(cmp_str("$rU", "kamailio"))
{
    # do interesting stuff here
}
...

4.49.  cmp_istr(str1, str2)

   The function returns true if the two parameters matches as string case
   insensitive comparison.

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

   Example 1.49. cmp_str usage
...
if(cmp_istr("$rU@you", "kamailio@YOU"))
{
    # do interesting stuff here
}
...

4.50.  starts_with(str1, str2)

   The function returns true if the first string starts with the second
   string.

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

   Example 1.50. starts_with usage
...
if (starts_with("$rU", "+358"))
{
    # do interesting stuff here
}
...

4.51.  ends_with(str1, str2)

   The function returns true if the first string ends with the second
   string. The parameters can contain variables.

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

   Example 1.51. ends_with usage
...
if (ends_with("$rU", "8800"))
{
    # do interesting stuff here
}
...

4.52.  str_find(str1, str2)

   The function returns true (greater than 0) if the str2 string is found
   in str1, case sensitive comparison.

   This function can be used from ANY_ROUTE.

   Example 1.52. str_find usage
...
if (str_find("$rU", "8800")) {
    # do interesting stuff here
}
...

4.53.  str_ifind(str1, str2)

   The function returns true (greater than 0) if the str2 string is found
   in str1, case insensitive comparison.

   This function can be used from ANY_ROUTE.

   Example 1.53. str_ifind usage
...
if (str_ifind("$rU", "Alice")) {
    # do interesting stuff here
}
...

4.54.  str_any_in(txt, clist)

   Return 1 (true) if any character in "clist" is found inside "txt". Both
   paramters can contain variables.

   This function can be used from ANY_ROUTE.

   Example 1.54. str_any_in usage
...
if (str_any_in("$hdr(X-Hdr)", ";',:")) {
    # do interesting stuff here
}
...

4.55.  set_body_multipart([txt, content_type][, boundary])

   Set multipart body to a SIP message. If called with no parameters, will
   convert present body to multipart.

   Meaning of the parameters is as follows:
     * txt - text for the body, can include pseudo-variables.
     * content_type - value of Content-Type header, can include
       pseudo-variables.
     * boundary - string to use as boundary, can include pseudo-variables.
       Default: unique-boundary-1

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

   The core will take care of the last boundary ending with "--",
   detecting which one is the last and fixing the others if needed.

   Note: it may be required that msg_apply_changes() from textopsx module
   has to be executed if there are other operations over the new body.

   Example 1.55. set_body_multipart usage
...
set_body_multipart("test", "text/plain", "delimiter");
msg_apply_changes();
append_body_part(...);
msg_apply_changes();

...

# Will produce:

...
Content-Type: multipart/mixed;boundary="delimiter"
Mime-Version: 1.0

--delimiter
Content-Type: text/plain

text

--delimiter
...

4.56.  append_body_part(txt, content_type[, content_disposition])

   Append a part on multipart body SIP message. Will use
   "unique-boundary-1" as boundary.

   Meaning of the parameters is as follows:
     * txt - text for the multipart body, can include pseudo-variables.
     * content_type - value of Content-Type header, can include
       pseudo-variables.
     * content_disposition - value of Content-Disposition header, can
       include pseudo-variables.

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

   The core will take care of the last boundary ending with "--",
   detecting which one is the last and fixing the others if needed.

   Note: it may be required that msg_apply_changes() from textopsx module
   has to be executed if there are other operations over the new body.

   Example 1.56. append_body_part usage
...
$var(b) = "7e Od 04 55 75 69 20 4d 61 6b 65 43 61 6c 6c";
append_body_part("$var(b)", "application/vnd.cirpack.isdn-ext", "signal;handling
=required");
msg_apply_changes();
...

# Will append this to the body:

...
Content-Type: application/vnd.cirpack.isdn-ext
Content-Disposition: signal;handling=required

7e Od 04 55 75 69 20 4d 61 6b 65 43 61 6c 6c

--unique-boundary-1
...

   If other headers should be added to a MIME body part, they can be
   appended after the value of the content-type parameter, separated by
   `\r\n` (at the very end do not add the '\r\n').

   Example 1.57. append_body_part with headers
...
$var(b) = "7e Od 04 55 75 69 20 4d 61 6b 65 43 61 6c 6c";
append_body_part("$var(b)", "application/vnd.cirpack.isdn-ext\r\nX-Header: xyz",
 "signal;handling=required");
msg_apply_changes();
...

# Will append this to the body:

...
Content-Type: application/vnd.cirpack.isdn-ext
X-Header: xyz
Content-Disposition: signal;handling=required

7e Od 04 55 75 69 20 4d 61 6b 65 43 61 6c 6c

--unique-boundary-1
...

4.57.  append_body_part_hex(txt, content_type[, content_disposition])

   Append a part on multipart body SIP message, with the content provided
   in hexa format. Will use "unique-boundary-1" as boundary.

   Meaning of the parameters is as follows:
     * txt - content for the multipart body in hexa format. Spaces can be
       used between the pairs of hexa digits to make it easier to read in
       the config, they are ignored and not added in the body part. The
       parameter can include pseudo-variables.
     * content_type - value of Content-Type header, can include
       pseudo-variables.
     * content_disposition - value of Content-Disposition header, can
       include pseudo-variables.

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

   The core will take care of the last boundary ending with "--",
   detecting which one is the last and fixing the others if needed.

   Note: it may be required that msg_apply_changes() from textopsx module
   has to be executed if there are other operations over the new body.

   Example 1.58. append_body_part_hex usage
...
$var(b) = "6b 61 6d 61 69 6c 69 6f";
append_body_part_hex("$var(b)", "application/my-custom-ext");
msg_apply_changes();
...

# Will append this to the body:

...
Content-Type: application/my-custom-ext

kamailio

--unique-boundary-1
...

   If other headers should be added to a MIME body part, see the docs for
   append_body_part(...) function.

4.58.  get_body_part(content_type, opv)

   Return the content of a multipart body SIP message, storing it in opv.

   Meaning of the parameters is as follows:
     * content_type - value of Content-Type header of the part to be
       returned. If more than one exists the first occurrence will be
       returned.
     * opv - variable name where to store the result.

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

   Example 1.59. get_body_part usage
...
get_body_part("application/vnd.cirpack.isdn-ext", "$var(pbody)");
...

4.59.  get_body_part_raw(content_type, opv)

   Return the content of a multipart body SIP message, including headers
   and boundary string, storing it in opv.

   Meaning of the parameters is as follows:
     * content_type - value of Content-Type header of the part to be
       returned. If more than one exists the first occurrence will be
       returned.
     * opv - variable name where to store the result.

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

   Example 1.60. get_body_part_raw usage
...
get_body_part("application/vnd.cirpack.isdn-ext", "$var(hbody)");
...

4.60.  remove_body_part(content_type)

   Remove a part on a multipart body SIP message.

   Meaning of the parameters is as follows:
     * content_type - value of Content-Type header of the part to be
       removed. If more than one exists the first occurrence will be
       removed.

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

   The core will take care of the last boundary ending with "--",
   detecting which one is the last and fixing the others if needed.

   Note: it may be required that msg_apply_changes() from textopsx module
   has to be executed if there are other operations over the new body.

   Example 1.61. remove_body_part usage
...
remove_body_part("application/vnd.cirpack.isdn-ext");
msg_apply_changes();
...

4.61.  regex_substring(itext, regexp, mindex, mcount, dpv)

   Search in text with given regular expression then set dpv
   pseudo-variable with the matched token at provided index.

   Meaning of the parameters is as follows:
     * itext - text to be searched (dynamic string)
     * regexp - regular expression (dynamic string)
     * mindex - index of the matched token (int or variable holding int)
     * mcount - the number of maximum expected matches (int or variable
       holding int)
     * dpv - variable to be set with matched token (static string with a
       name of a variable)

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

   Note that the regular expression extended is used. More info at:
   https://www.regular-expressions.info/posix.html.

   Example 1.62. _regex_substring usage
        ...
        regex_substring("___ abc123def ___ ghi456 ___", "([a-z]*)([0-9]+)([a-z]*
)",
                        1, 3, "$var(asd)");
        xlog("L_WARN","RESULT: $var(asd)\r\n");
        ------
        result:
        abc
        ----
        ...

Chapter 2. Developer Guide

   Table of Contents

   1. Functions

        1.1. load_textops(*import_structure)

1. Functions

   1.1. load_textops(*import_structure)

1.1.  load_textops(*import_structure)

   For programmatic use only--import the Textops API.

   Meaning of the parameters is as follows:
     * import_structure - Pointer to the import structure - see “struct
       textops_binds” in modules/textops/api.h
