modules_k/textops/README
31ccf6a2
 textops Module
 
 Andrei Pelinescu-Onciul
 
    FhG FOKUS
d34518a2
    <pelinescu-onciul@fokus.fraunhofer.de>
31ccf6a2
 
 Edited by
 
 Andrei Pelinescu-Onciul
 
d34518a2
    <pelinescu-onciul@fokus.fraunhofer.de>
 
d77df08a
 Edited by
 
c7149915
 Daniel-Constantin Mierla
 
d34518a2
    <miconda@gmail.com>
 
92e83779
 Edited by
 
 Juha Heinanen
 
    <jh@tutpro.com>
 
    Copyright © 2003 FhG FOKUS
d77df08a
    Revision History
0e24d9be
    Revision $Revision$ $Date$
      __________________________________________________________________
31ccf6a2
 
    Table of Contents
d77df08a
 
9fc784c6
    1. Admin Guide
31ccf6a2
 
0e24d9be
         1. Overview
 
               1.1. Known Limitations
 
         2. Dependencies
 
               2.1. Kamailio Modules
               2.2. External Libraries or Applications
 
         3. Exported Functions
 
               3.1. search(re)
               3.2. search_body(re)
               3.3. search_append(re, txt)
               3.4. search_append_body(re, txt)
               3.5. replace(re, txt)
               3.6. replace_body(re, txt)
               3.7. replace_all(re, txt)
               3.8. replace_body_all(re, txt)
               3.9. replace_body_atonce(re, txt)
               3.10. subst('/re/repl/flags')
               3.11. subst_uri('/re/repl/flags')
               3.12. subst_user('/re/repl/flags')
               3.13. subst_body('/re/repl/flags')
               3.14. set_body(txt,content_type)
               3.15. set_reply_body(txt,content_type)
               3.16. filter_body(content_type)
               3.17. append_to_reply(txt)
               3.18. append_hf(txt)
               3.19. append_hf(txt, hdr)
               3.20. insert_hf(txt)
               3.21. insert_hf(txt, hdr)
               3.22. append_urihf(prefix, suffix)
               3.23. is_present_hf(hf_name)
               3.24. is_present_hf_re(hf_name_re)
               3.25. append_time()
               3.26. is_method(name)
               3.27. remove_hf(hname)
               3.28. remove_hf_re(re)
               3.29. has_body(), has_body(mime)
4c927f8e
               3.30. is_audio_on_hold()
               3.31. is_privacy(privacy_type)
               3.32. cmp_str(str1, str2)
               3.33. cmp_istr(str1, str2)
               3.34. starts_with(str1, str2)
0e24d9be
 
         4. Known Limitations
31ccf6a2
 
995f8acd
    2. Developer Guide
 
0e24d9be
         1. Functions
995f8acd
 
0e24d9be
               1.1. load_textops(*import_structure)
995f8acd
 
31ccf6a2
    List of Examples
d77df08a
 
    1.1. search usage
    1.2. search_body usage
    1.3. search_append usage
    1.4. search_append_body usage
    1.5. replace usage
    1.6. replace_body usage
    1.7. replace_all usage
    1.8. replace_body_all usage
d735982b
    1.9. replace_body_atonce usage
    1.10. subst usage
    1.11. subst_uri usage
    1.12. subst usage
    1.13. subst_body usage
dab29be0
    1.14. set_body usage
eb3711c4
    1.15. set_reply_body usage
dab29be0
    1.16. filter_body usage
    1.17. append_to_reply usage
3111582a
    1.18. append_hf usage
dab29be0
    1.19. append_hf usage
3111582a
    1.20. insert_hf usage
dab29be0
    1.21. insert_hf usage
    1.22. append_urihf usage
    1.23. is_present_hf usage
    1.24. is_present_hf_re usage
    1.25. append_time usage
    1.26. is_method usage
    1.27. remove_hf usage
    1.28. remove_hf_re usage
    1.29. has_body usage
4c927f8e
    1.30. is_audio_on_hold usage
    1.31. is_privacy usage
dab29be0
    1.32. cmp_str usage
4c927f8e
    1.33. cmp_str usage
    1.34. starts_with usage
31ccf6a2
 
9fc784c6
 Chapter 1. Admin Guide
31ccf6a2
 
0e24d9be
    Table of Contents
31ccf6a2
 
0e24d9be
    1. Overview
 
         1.1. Known Limitations
 
    2. Dependencies
 
         2.1. Kamailio Modules
         2.2. External Libraries or Applications
 
    3. Exported Functions
 
         3.1. search(re)
         3.2. search_body(re)
         3.3. search_append(re, txt)
         3.4. search_append_body(re, txt)
         3.5. replace(re, txt)
         3.6. replace_body(re, txt)
         3.7. replace_all(re, txt)
         3.8. replace_body_all(re, txt)
         3.9. replace_body_atonce(re, txt)
         3.10. subst('/re/repl/flags')
         3.11. subst_uri('/re/repl/flags')
         3.12. subst_user('/re/repl/flags')
         3.13. subst_body('/re/repl/flags')
         3.14. set_body(txt,content_type)
         3.15. set_reply_body(txt,content_type)
         3.16. filter_body(content_type)
         3.17. append_to_reply(txt)
         3.18. append_hf(txt)
         3.19. append_hf(txt, hdr)
         3.20. insert_hf(txt)
         3.21. insert_hf(txt, hdr)
         3.22. append_urihf(prefix, suffix)
         3.23. is_present_hf(hf_name)
         3.24. is_present_hf_re(hf_name_re)
         3.25. append_time()
         3.26. is_method(name)
         3.27. remove_hf(hname)
         3.28. remove_hf_re(re)
         3.29. has_body(), has_body(mime)
4c927f8e
         3.30. is_audio_on_hold()
         3.31. is_privacy(privacy_type)
         3.32. cmp_str(str1, str2)
         3.33. cmp_istr(str1, str2)
         3.34. starts_with(str1, str2)
0e24d9be
 
    4. Known Limitations
 
 1. Overview
 
    1.1. Known Limitations
 
    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 and replace, Perl-like
    substitutions, checks for method type, header presence, insert of new
    header and date, etc.
 
 1.1. Known Limitations
 
92e83779
    search ignores folded lines. For example, search(“(From|f):.*@foo.bar”)
0e24d9be
    doesn't match the following From header field:
31ccf6a2
 From: medabeda
  <sip:medameda@foo.bar>;tag=1234
 
0e24d9be
 2. Dependencies
31ccf6a2
 
0e24d9be
    2.1. Kamailio Modules
    2.2. External Libraries or Applications
 
 2.1. Kamailio Modules
31ccf6a2
 
    The following modules must be loaded before this module:
37e4f522
      * No dependencies on other Kamailio modules.
31ccf6a2
 
0e24d9be
 2.2. External Libraries or Applications
31ccf6a2
 
0e24d9be
    The following libraries or applications must be installed before
    running Kamailio with this module loaded:
31ccf6a2
      * None.
 
0e24d9be
 3. Exported Functions
 
    3.1. search(re)
    3.2. search_body(re)
    3.3. search_append(re, txt)
    3.4. search_append_body(re, txt)
    3.5. replace(re, txt)
    3.6. replace_body(re, txt)
    3.7. replace_all(re, txt)
    3.8. replace_body_all(re, txt)
    3.9. replace_body_atonce(re, txt)
    3.10. subst('/re/repl/flags')
    3.11. subst_uri('/re/repl/flags')
    3.12. subst_user('/re/repl/flags')
    3.13. subst_body('/re/repl/flags')
    3.14. set_body(txt,content_type)
    3.15. set_reply_body(txt,content_type)
    3.16. filter_body(content_type)
    3.17. append_to_reply(txt)
    3.18. append_hf(txt)
    3.19. append_hf(txt, hdr)
    3.20. insert_hf(txt)
    3.21. insert_hf(txt, hdr)
    3.22. append_urihf(prefix, suffix)
    3.23. is_present_hf(hf_name)
    3.24. is_present_hf_re(hf_name_re)
    3.25. append_time()
    3.26. is_method(name)
    3.27. remove_hf(hname)
    3.28. remove_hf_re(re)
    3.29. has_body(), has_body(mime)
4c927f8e
    3.30. is_audio_on_hold()
    3.31. is_privacy(privacy_type)
    3.32. cmp_str(str1, str2)
    3.33. cmp_istr(str1, str2)
    3.34. starts_with(str1, str2)
0e24d9be
 
92e83779
 3.1.  search(re)
31ccf6a2
 
    Searches for the re in the message.
 
    Meaning of the parameters is as follows:
      * re - Regular expression.
 
bfcbd22f
    This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE,
    FAILURE_ROUTE, BRANCH_ROUTE.
 
d77df08a
    Example 1.1. search usage
31ccf6a2
 ...
7846e3c8
 if ( search("[Ss][Ii][Pp]") ) { /*....*/ };
31ccf6a2
 ...
 
92e83779
 3.2.  search_body(re)
2d65b0db
 
    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.
 
d77df08a
    Example 1.2. search_body usage
2d65b0db
 ...
7846e3c8
 if ( search_body("[Ss][Ii][Pp]") ) { /*....*/ };
2d65b0db
 ...
 
92e83779
 3.3.  search_append(re, txt)
31ccf6a2
 
    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.
 
bfcbd22f
    This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE,
    FAILURE_ROUTE, BRANCH_ROUTE.
 
d77df08a
    Example 1.3. search_append usage
31ccf6a2
 ...
ac1ffec9
 search_append("[Oo]pen[Ss]er", " SIP Proxy");
31ccf6a2
 ...
 
92e83779
 3.4.  search_append_body(re, txt)
2d65b0db
 
0e24d9be
    Searches for the first match of re in the body of the message and
    appends txt after it.
2d65b0db
 
    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.
 
d77df08a
    Example 1.4. search_append_body usage
2d65b0db
 ...
 search_append_body("[Oo]pen[Ss]er", " SIP Proxy");
 ...
 
92e83779
 3.5.  replace(re, txt)
31ccf6a2
 
    Replaces the first occurrence of re with txt.
 
    Meaning of the parameters is as follows:
      * re - Regular expression.
      * txt - String.
 
bfcbd22f
    This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE,
    FAILURE_ROUTE, BRANCH_ROUTE.
 
d77df08a
    Example 1.5. replace usage
31ccf6a2
 ...
9b64b9f3
 replace("openser", "Kamailio SIP Proxy");
31ccf6a2
 ...
 
92e83779
 3.6.  replace_body(re, txt)
2d65b0db
 
0e24d9be
    Replaces the first occurrence of re in the body of the message with
    txt.
2d65b0db
 
    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.
 
d77df08a
    Example 1.6. replace_body usage
2d65b0db
 ...
9b64b9f3
 replace_body("openser", "Kamailio SIP Proxy");
2d65b0db
 ...
 
92e83779
 3.7.  replace_all(re, txt)
31ccf6a2
 
    Replaces all occurrence of re with txt.
 
    Meaning of the parameters is as follows:
      * re - Regular expression.
      * txt - String.
 
bfcbd22f
    This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE,
    FAILURE_ROUTE, BRANCH_ROUTE.
 
d77df08a
    Example 1.7. replace_all usage
31ccf6a2
 ...
9b64b9f3
 replace_all("openser", "Kamailio SIP Proxy");
31ccf6a2
 ...
 
92e83779
 3.8.  replace_body_all(re, txt)
2d65b0db
 
0e24d9be
    Replaces all occurrence of re in the body of the message with txt.
    Matching is done on a per-line basis.
2d65b0db
 
    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.
 
d77df08a
    Example 1.8. replace_body_all usage
2d65b0db
 ...
9b64b9f3
 replace_body_all("openser", "Kamailio SIP Proxy");
2d65b0db
 ...
 
92e83779
 3.9.  replace_body_atonce(re, txt)
d735982b
 
0e24d9be
    Replaces all occurrence of re in the body of the message with txt.
    Matching is done over the whole body.
d735982b
 
    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.9. replace_body_atonce usage
 ...
 # strip the whole body from the message:
 if(has_body() && replace_body_atonce("^.+$", ""))
         remove_hf("Content-Type");
 ...
 
92e83779
 3.10.  subst('/re/repl/flags')
31ccf6a2
 
    Replaces re with repl (sed or perl like).
 
    Meaning of the parameters is as follows:
0e24d9be
      * '/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).
2b885bfa
        're' - is regular expresion
0e24d9be
        'repl' - is replacement string - may contain pseudo-varibales
2b885bfa
        'flags' - substitution flags (i - ignore case, g - global)
31ccf6a2
 
bfcbd22f
    This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE,
    FAILURE_ROUTE, BRANCH_ROUTE.
 
d735982b
    Example 1.10. subst usage
31ccf6a2
 ...
 # 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') ) {};
2b885bfa
 
0e24d9be
 # 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') )
  {};
2b885bfa
 
31ccf6a2
 ...
 
92e83779
 3.11.  subst_uri('/re/repl/flags')
31ccf6a2
 
0e24d9be
    Runs the re substitution on the message uri (like subst but works only
    on the uri)
31ccf6a2
 
    Meaning of the parameters is as follows:
0e24d9be
      * '/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).
2b885bfa
        're' - is regular expresion
0e24d9be
        'repl' - is replacement string - may contain pseudo-varibales
2b885bfa
        'flags' - substitution flags (i - ignore case, g - global)
31ccf6a2
 
bfcbd22f
    This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE,
    FAILURE_ROUTE, BRANCH_ROUTE.
 
d735982b
    Example 1.11. subst_uri usage
31ccf6a2
 ...
989206bd
 # adds 3463 prefix to numeric uris, and save the original uri (\0 match)
31ccf6a2
 # as a parameter: orig_uri (just an example)
 if (subst_uri('/^sip:([0-9]+)@(.*)$/sip:3463\1@\2;orig_uri=\0/i')){$
 
0e24d9be
 # adds the avp 'uri_prefix' as prefix to numeric uris, and save the original
2b885bfa
 # uri (\0 match) as a parameter: orig_uri (just an example)
0e24d9be
 if (subst_uri('/^sip:([0-9]+)@(.*)$/sip:$avp(uri_prefix)\1@\2;orig_uri=\0/i')){$
2b885bfa
 
31ccf6a2
 ...
 
92e83779
 3.12.  subst_user('/re/repl/flags')
31ccf6a2
 
0e24d9be
    Runs the re substitution on the message uri (like subst_uri but works
    only on the user portion of the uri)
31ccf6a2
 
    Meaning of the parameters is as follows:
0e24d9be
      * '/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).
2b885bfa
        're' - is regular expresion
0e24d9be
        'repl' - is replacement string - may contain pseudo-varibales
2b885bfa
        'flags' - substitution flags (i - ignore case, g - global)
31ccf6a2
 
bfcbd22f
    This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE,
    FAILURE_ROUTE, BRANCH_ROUTE.
 
d735982b
    Example 1.12. subst usage
31ccf6a2
 ...
 # adds 3463 prefix to uris ending with 3642 (just an example)
 if (subst_user('/3642$/36423463/')){$
 
2b885bfa
 ...
989206bd
 # adds avp 'user_prefix' as prefix to username in r-uri ending with 3642
2b885bfa
 if (subst_user('/(.*)3642$/$avp(user_prefix)\13642/')){$
 
31ccf6a2
 ...
 
92e83779
 3.13.  subst_body('/re/repl/flags')
2d65b0db
 
0e24d9be
    Replaces re with repl (sed or perl like) in the body of the message.
2d65b0db
 
    Meaning of the parameters is as follows:
0e24d9be
      * '/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).
2d65b0db
        're' - is regular expresion
0e24d9be
        'repl' - is replacement string - may contain pseudo-varibales
2d65b0db
        'flags' - substitution flags (i - ignore case, g - global)
 
    This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE,
    FAILURE_ROUTE, BRANCH_ROUTE.
 
d735982b
    Example 1.13. subst_body usage
2d65b0db
 ...
7935fb4a
 if ( subst_body('/^o=(.*) /o=$fU /') ) {};
2d65b0db
 
 ...
193208b3
 
92e83779
 3.14.  set_body(txt,content_type)
3111582a
 
dab29be0
    Set body to a SIP message.
3111582a
 
    Meaning of the parameters is as follows:
dab29be0
      * txt - text for the body, can include pseudo-variables.
      * content_type - value of Content-Type header, can include
        pseudo-variables.
3111582a
 
    This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE,
    FAILURE_ROUTE, BRANCH_ROUTE.
 
dab29be0
    Example 1.14. set_body usage
3111582a
 ...
dab29be0
 set_body("test", "text/plain");
3111582a
 ...
 
92e83779
 3.15.  set_reply_body(txt,content_type)
dab29be0
 
    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.
 
eb3711c4
    Example 1.15. set_reply_body usage
dab29be0
 ...
eb3711c4
 set_reply_body("test", "text/plain");
dab29be0
 ...
 
92e83779
 3.16.  filter_body(content_type)
193208b3
 
0e24d9be
    Filters multipart/mixed body by leaving out all other body parts except
    the first body part of given type.
193208b3
 
    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.
 
dab29be0
    Example 1.16. filter_body usage
193208b3
 ...
 if (has_body("multipart/mixed")) {
     if (filter_body("application/sdp") {
64cf3dc8
         remove_hf("Content-Type");
         append_hf("Content-Type: application/sdp\r\n");
193208b3
     } else {
         xlog("Body part application/sdp not found\n");
     }
 }
 ...
 
92e83779
 3.17.  append_to_reply(txt)
31ccf6a2
 
1841279d
    Append txt as header to the reply.
31ccf6a2
 
    Meaning of the parameters is as follows:
1841279d
      * txt - String which may contains pseudo-variables.
31ccf6a2
 
45b91eae
    This function can be used from REQUEST_ROUTE, BRANCH_ROUTE,
7935fb4a
    FAILURE_ROUTE, ERROR_ROUTE.
bfcbd22f
 
dab29be0
    Example 1.17. append_to_reply usage
31ccf6a2
 ...
 append_to_reply("Foo: bar\r\n");
1841279d
 append_to_reply("Foo: $rm at $Ts\r\n");
31ccf6a2
 ...
 
92e83779
 3.18.  append_hf(txt)
31ccf6a2
 
c7149915
    Appends 'txt' as header after the last header field.
31ccf6a2
 
    Meaning of the parameters is as follows:
c7149915
      * txt - Header field to be appended. The value can contain
        pseudo-variables which will be replaced at run time.
31ccf6a2
 
0e24d9be
    Note: Headers which are added in main route cannot be removed in
    further routes (e.g. failure routes). So, the idea is not to add there
    any headers that you might want to remove later. To add headers
    temporarely use the branch route because the changes you do there are
    per-branch.
62ab3143
 
bfcbd22f
    This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE,
    FAILURE_ROUTE, BRANCH_ROUTE.
 
dab29be0
    Example 1.18. append_hf usage
31ccf6a2
 ...
 append_hf("P-hint: VOICEMAIL\r\n");
c7149915
 append_hf("From-username: $fU\r\n");
 ...
 
92e83779
 3.19.  append_hf(txt, hdr)
c7149915
 
    Appends 'txt' as header after first 'hdr' header field.
 
    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.
      * hdr - Header name after which the 'txt' is appended.
 
    This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE,
    FAILURE_ROUTE, BRANCH_ROUTE.
 
dab29be0
    Example 1.19. append_hf usage
c7149915
 ...
 append_hf("P-hint: VOICEMAIL\r\n", "Call-ID");
 append_hf("From-username: $fU\r\n", "Call-ID");
 ...
 
92e83779
 3.20.  insert_hf(txt)
c7149915
 
    Inserts 'txt' as header before the first header field.
 
    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.
 
    This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE,
    FAILURE_ROUTE, BRANCH_ROUTE.
 
dab29be0
    Example 1.20. insert_hf usage
c7149915
 ...
 insert_hf("P-hint: VOICEMAIL\r\n");
 insert_hf("To-username: $tU\r\n");
 ...
 
92e83779
 3.21.  insert_hf(txt, hdr)
c7149915
 
    Inserts 'txt' as header before first 'hdr' header field.
 
    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.
      * hdr - Header name before which the 'txt' is inserted.
 
    This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE,
    FAILURE_ROUTE, BRANCH_ROUTE.
 
dab29be0
    Example 1.21. insert_hf usage
c7149915
 ...
 insert_hf("P-hint: VOICEMAIL\r\n", "Call-ID");
 insert_hf("To-username: $tU\r\n", "Call-ID");
31ccf6a2
 ...
 
92e83779
 3.22.  append_urihf(prefix, suffix)
31ccf6a2
 
    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).
 
bfcbd22f
    This function can be used from REQUEST_ROUTE, FAILURE_ROUTE,
    BRANCH_ROUTE.
 
dab29be0
    Example 1.22. append_urihf usage
31ccf6a2
 ...
 append_urihf("CC-Diversion: ", "\r\n");
 ...
 
92e83779
 3.23.  is_present_hf(hf_name)
31ccf6a2
 
    Return true if a header field is present in message.
 
d77df08a
 Note
31ccf6a2
 
0e24d9be
    The function is also able to distinguish the compact names. For exmaple
92e83779
    “From” will match with “f”
31ccf6a2
 
    Meaning of the parameters is as follows:
ac1ffec9
      * hf_name - Header field name.(long or compact form)
31ccf6a2
 
bfcbd22f
    This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE,
    FAILURE_ROUTE, BRANCH_ROUTE.
 
dab29be0
    Example 1.23. is_present_hf usage
31ccf6a2
 ...
 if (is_present_hf("From")) log(1, "From HF Present");
 ...
 
92e83779
 3.24.  is_present_hf_re(hf_name_re)
846096f4
 
0e24d9be
    Return true if a header field whose name matches regular expression
    'hf_name_re' is present in message.
846096f4
 
    Meaning of the parameters is as follows:
      * hf_name_re - Regular expression to match header field name.
 
    This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE,
    FAILURE_ROUTE, BRANCH_ROUTE.
 
dab29be0
    Example 1.24. is_present_hf_re usage
846096f4
 ...
0e24d9be
 if (is_present_hf_re("^P-")) log(1, "There are headers starting with P-\n");
846096f4
 ...
 
92e83779
 3.25.  append_time()
31ccf6a2
 
0e24d9be
    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
92e83779
    'registrar' module. Header format is: “Date: %a, %d %b %Y %H:%M:%S
    GMT”, with the legend:
31ccf6a2
      * %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
 
bfcbd22f
    Return true if a header was succesfully appended.
 
    This function can be used from REQUEST_ROUTE, FAILURE_ROUTE,
    BRANCH_ROUTE.
31ccf6a2
 
dab29be0
    Example 1.25. append_time usage
31ccf6a2
 ...
 append_time();
 ...
 
92e83779
 3.26.  is_method(name)
d51e24a2
 
0e24d9be
    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.
d51e24a2
 
5160bbf3
    The 'name' can be a list of methods in the form of
0e24d9be
    '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).
5160bbf3
 
0e24d9be
    If used for replies, the function tests the value of method field from
    CSeq header.
d51e24a2
 
    Meaning of the parameters is as follows:
      * name - SIP method name
 
bfcbd22f
    This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE,
1841279d
    FAILURE_ROUTE, and BRANCH_ROUTE.
bfcbd22f
 
dab29be0
    Example 1.26. is_method usage
d51e24a2
 ...
 if(is_method("INVITE"))
 {
     # process INVITEs here
 }
5160bbf3
 if(is_method("OPTION|UPDATE"))
 {
     # process OPTIONs and UPDATEs here
 }
d51e24a2
 ...
 
92e83779
 3.27.  remove_hf(hname)
5b6af582
 
92e83779
    Remove from message all headers with name “hname”
5b6af582
 
    Returns true if at least one header is found and removed.
 
    Meaning of the parameters is as follows:
      * hname - header name to be removed.
 
    This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE,
    FAILURE_ROUTE and BRANCH_ROUTE.
 
dab29be0
    Example 1.27. remove_hf usage
5b6af582
 ...
 if(remove_hf("User-Agent"))
 {
     # User Agent header removed
 }
 ...
 
92e83779
 3.28.  remove_hf_re(re)
d3791a9f
 
0e24d9be
    Remove from message all headers with name matching regular expression
92e83779
    “re”
d3791a9f
 
    Returns true if at least one header is found and removed.
 
    Meaning of the parameters is as follows:
0e24d9be
      * re - regular expression to match the header name to be removed.
d3791a9f
 
    This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE,
    FAILURE_ROUTE and BRANCH_ROUTE.
 
dab29be0
    Example 1.28. remove_hf_re usage
d3791a9f
 ...
 if(remove_hf_re("^P-"))
 {
     # All headers starting with "P-" removed
 }
 ...
 
92e83779
 3.29.  has_body(), has_body(mime)
f05cccfe
 
0e24d9be
    The function returns true if the SIP message has a body attached. The
92e83779
    checked includes also the “Content-Lenght” header presence and value.
f05cccfe
 
0c4b0f77
    If a parameter is given, the mime described will be also checked
92e83779
    against the “Content-Type” header.
f05cccfe
 
    Meaning of the parameters is as follows:
92e83779
      * mime - mime to be checked against the “Content-Type” header. If not
0e24d9be
        present or 0, this check will be disabled.
f05cccfe
 
    This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE,
    FAILURE_ROUTE and BRANCH_ROUTE.
 
dab29be0
    Example 1.29. has_body usage
f05cccfe
 ...
 if(has_body("application/sdp"))
 {
     # do interesting stuff here
 }
 ...
 
4c927f8e
 3.30.  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.
 
    This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE,
    FAILURE_ROUTE and BRANCH_ROUTE.
 
    Example 1.30. is_audio_on_hold usage
 ...
 if(is_audio_on_hold())
 {
     # do interesting stuff here
 }
 ...
 
 3.31.  is_privacy(privacy_type)
2b3b76cc
 
0e24d9be
    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.
2b3b76cc
 
    This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE,
    FAILURE_ROUTE and BRANCH_ROUTE.
 
4c927f8e
    Example 1.31. is_privacy usage
2b3b76cc
 ...
 if(is_privacy("id"))
 {
     # do interesting stuff here
 }
 ...
 
4c927f8e
 3.32.  cmp_str(str1, str2)
588c00cb
 
0e24d9be
    The function returns true if the two parameters matches as string case
    sensitive comparison.
588c00cb
 
    This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE,
    FAILURE_ROUTE and BRANCH_ROUTE.
 
4c927f8e
    Example 1.32. cmp_str usage
588c00cb
 ...
 if(cmp_str("$rU", "kamailio"))
 {
     # do interesting stuff here
 }
 ...
 
4c927f8e
 3.33.  cmp_istr(str1, str2)
588c00cb
 
0e24d9be
    The function returns true if the two parameters matches as string case
    insensitive comparison.
588c00cb
 
    This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE,
    FAILURE_ROUTE and BRANCH_ROUTE.
 
4c927f8e
    Example 1.33. cmp_str usage
588c00cb
 ...
 if(cmp_istr("$rU@you", "kamailio@YOU"))
 {
     # do interesting stuff here
 }
 ...
 
4c927f8e
 3.34.  starts_with(str1, str2)
92e83779
 
    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.
 
4c927f8e
    Example 1.34. starts_with usage
92e83779
 ...
2759deb3
 if (starts_with("$rU", "+358"))
92e83779
 {
     # do interesting stuff here
 }
 ...
 
0e24d9be
 4. Known Limitations
 
    Search functions are applied to the original request, i.e., they ignore
    all changes resulting from message processing in Kamailio script.
995f8acd
 
 Chapter 2. Developer Guide
 
0e24d9be
    Table of Contents
 
    1. Functions
 
         1.1. load_textops(*import_structure)
 
 1. Functions
 
    1.1. load_textops(*import_structure)
995f8acd
 
92e83779
 1.1.  load_textops(*import_structure)
995f8acd
 
    For programmatic use only--import the Textops API.
 
    Meaning of the parameters is as follows:
92e83779
      * import_structure - Pointer to the import structure - see “struct
        textops_binds” in modules/textops/api.h