textops: refreshing readme from xml documentation

modules/textops/README

@@ -23,7 +23,7 @@ Juha Heinanen
 
    <[email protected]>
 
-   Copyright © 2003 FhG FOKUS
+   Copyright © 2003 FhG FOKUS
      __________________________________________________________________
 
    Table of Contents
@@ -81,7 +81,9 @@ Juha Heinanen
               3.38. append_body_part(txt,content_type[,
                       content_disposition])
 
-              3.39. remove_body_part(content_type)
+              3.39. get_body_part(content_type, opv)
+              3.40. get_body_part_raw(content_type, opv)
+              3.41. remove_body_part(content_type)
 
         4. Known Limitations
 
@@ -131,7 +133,9 @@ Juha Heinanen
    1.36. starts_with usage
    1.37. set_body_multipart usage
    1.38. append_body_part usage
-   1.39. remove_body_part usage
+   1.39. get_body_part usage
+   1.40. get_body_part_raw usage
+   1.41. remove_body_part usage
 
 Chapter 1. Admin Guide
 
@@ -186,7 +190,9 @@ Chapter 1. Admin Guide
         3.36. starts_with(str1, str2)
         3.37. set_body_multipart([txt,content_type][,boundary])
         3.38. append_body_part(txt,content_type[, content_disposition])
-        3.39. remove_body_part(content_type)
+        3.39. get_body_part(content_type, opv)
+        3.40. get_body_part_raw(content_type, opv)
+        3.41. remove_body_part(content_type)
 
    4. Known Limitations
 
@@ -203,7 +209,7 @@ Chapter 1. Admin Guide
 
 1.1. Known Limitations
 
-   search ignores folded lines. For example, search(“(From|f):.*@foo.bar�)
+   search ignores folded lines. For example, search("(From|f):.*@foo.bar")
    doesn't match the following From header field:
 From: medabeda
  <sip:[email protected]>;tag=1234
@@ -264,9 +270,11 @@ From: medabeda
    3.36. starts_with(str1, str2)
    3.37. set_body_multipart([txt,content_type][,boundary])
    3.38. append_body_part(txt,content_type[, content_disposition])
-   3.39. remove_body_part(content_type)
+   3.39. get_body_part(content_type, opv)
+   3.40. get_body_part_raw(content_type, opv)
+   3.41. remove_body_part(content_type)
 
-3.1.  search(re)
+3.1. search(re)
 
    Searches for the re in the message.
 
@@ -281,7 +289,7 @@ From: medabeda
 if ( search("[Ss][Ii][Pp]") ) { /*....*/ };
 ...
 
-3.2.  search_body(re)
+3.2. search_body(re)
 
    Searches for the re in the body of the message.
 
@@ -296,7 +304,7 @@ if ( search("[Ss][Ii][Pp]") ) { /*....*/ };
 if ( search_body("[Ss][Ii][Pp]") ) { /*....*/ };
 ...
 
-3.3.  search_hf(hf, re, flags)
+3.3. search_hf(hf, re, flags)
 
    Searches for the re in the body of a header field.
 
@@ -315,7 +323,7 @@ if ( search_body("[Ss][Ii][Pp]") ) { /*....*/ };
 if ( search_hf("From", ":test@", "a") ) { /*....*/ };
 ...
 
-3.4.  search_append(re, txt)
+3.4. search_append(re, txt)
 
    Searches for the first match of re and appends txt after it.
 
@@ -331,7 +339,7 @@ if ( search_hf("From", ":test@", "a") ) { /*....*/ };
 search_append("[Oo]pen[Ss]er", " SIP Proxy");
 ...
 
-3.5.  search_append_body(re, txt)
+3.5. search_append_body(re, txt)
 
    Searches for the first match of re in the body of the message and
    appends txt after it.
@@ -348,7 +356,7 @@ search_append("[Oo]pen[Ss]er", " SIP Proxy");
 search_append_body("[Oo]pen[Ss]er", " SIP Proxy");
 ...
 
-3.6.  replace(re, txt)
+3.6. replace(re, txt)
 
    Replaces the first occurrence of re with txt.
 
@@ -364,7 +372,7 @@ search_append_body("[Oo]pen[Ss]er", " SIP Proxy");
 replace("openser", "Kamailio SIP Proxy");
 ...
 
-3.7.  replace_body(re, txt)
+3.7. replace_body(re, txt)
 
    Replaces the first occurrence of re in the body of the message with
    txt.
@@ -381,7 +389,7 @@ replace("openser", "Kamailio SIP Proxy");
 replace_body("openser", "Kamailio SIP Proxy");
 ...
 
-3.8.  replace_all(re, txt)
+3.8. replace_all(re, txt)
 
    Replaces all occurrence of re with txt.
 
@@ -397,7 +405,7 @@ replace_body("openser", "Kamailio SIP Proxy");
 replace_all("openser", "Kamailio SIP Proxy");
 ...
 
-3.9.  replace_body_all(re, txt)
+3.9. 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.
@@ -414,7 +422,7 @@ replace_all("openser", "Kamailio SIP Proxy");
 replace_body_all("openser", "Kamailio SIP Proxy");
 ...
 
-3.10.  replace_body_atonce(re, txt)
+3.10. 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.
@@ -433,7 +441,7 @@ if(has_body() && replace_body_atonce("^.+$", ""))
         remove_hf("Content-Type");
 ...
 
-3.11.  subst('/re/repl/flags')
+3.11. subst('/re/repl/flags')
 
    Replaces re with repl (sed or perl like).
 
@@ -454,12 +462,12 @@ if(has_body() && replace_body_atonce("^.+$", ""))
 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')
-) {};
+if ( subst('/^To:(.*)sip:[^@]*@[a-zA-Z0-9.]+(.*)$/t:\1$avp(sip_address)\2/ig') )
+ {};
 
 ...
 
-3.12.  subst_uri('/re/repl/flags')
+3.12. subst_uri('/re/repl/flags')
 
    Runs the re substitution on the message uri (like subst but works only
    on the uri)
@@ -483,12 +491,11 @@ 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')){
-$
+if (subst_uri('/^sip:([0-9]+)@(.*)$/sip:$avp(uri_prefix)\1@\2;orig_uri=\0/i')){$
 
 ...
 
-3.13.  subst_user('/re/repl/flags')
+3.13. 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)
@@ -515,7 +522,7 @@ if (subst_user('/(.*)3642$/$avp(user_prefix)\13642/')){$
 
 ...
 
-3.14.  subst_body('/re/repl/flags')
+3.14. subst_body('/re/repl/flags')
 
    Replaces re with repl (sed or perl like) in the body of the message.
 
@@ -536,7 +543,7 @@ if ( subst_body('/^o=(.*) /o=$fU /') ) {};
 
 ...
 
-3.15.  subst_hf(hf, subexp, flags)
+3.15. subst_hf(hf, subexp, flags)
 
    Perl-like substitutions in the body of a header field.
 
@@ -556,7 +563,7 @@ if ( subst_body('/^o=(.*) /o=$fU /') ) {};
 if ( subst_hf("From", "/:test@/:best@/", "a") ) { /*....*/ };
 ...
 
-3.16.  set_body(txt,content_type)
+3.16. set_body(txt,content_type)
 
    Set body to a SIP message.
 
@@ -573,7 +580,7 @@ if ( subst_hf("From", "/:test@/:best@/", "a") ) { /*....*/ };
 set_body("test", "text/plain");
 ...
 
-3.17.  set_reply_body(txt,content_type)
+3.17. set_reply_body(txt,content_type)
 
    Set body to a SIP reply to be generated by Kamailio.
 
@@ -590,7 +597,7 @@ set_body("test", "text/plain");
 set_reply_body("test", "text/plain");
 ...
 
-3.18.  filter_body(content_type)
+3.18. filter_body(content_type)
 
    Filters multipart/mixed body by leaving out all other body parts except
    the first body part of given type.
@@ -613,7 +620,7 @@ if (has_body("multipart/mixed")) {
 }
 ...
 
-3.19.  append_to_reply(txt)
+3.19. append_to_reply(txt)
 
    Append txt as header to the reply.
 
@@ -629,7 +636,7 @@ append_to_reply("Foo: bar\r\n");
 append_to_reply("Foo: $rm at $Ts\r\n");
 ...
 
-3.20.  append_hf(txt[, hdr])
+3.20. append_hf(txt[, hdr])
 
    Appends 'txt' as header after first header field or after last 'hdr'
    header field.
@@ -648,7 +655,7 @@ append_hf("P-hint: VOICEMAIL\r\n");
 append_hf("From-username: $fU\r\n", "Call-ID");
 ...
 
-3.21.  insert_hf(txt[, hdr])
+3.21. insert_hf(txt[, hdr])
 
    Inserts 'txt' as header before the first header field or before first
    'hdr' header field if 'hdr' is given.
@@ -669,7 +676,7 @@ insert_hf("P-hint: VOICEMAIL\r\n", "Call-ID");
 insert_hf("To-username: $tU\r\n", "Call-ID");
 ...
 
-3.22.  append_urihf(prefix, suffix)
+3.22. append_urihf(prefix, suffix)
 
    Append header field name with original Request-URI in middle.
 
@@ -685,14 +692,14 @@ insert_hf("To-username: $tU\r\n", "Call-ID");
 append_urihf("CC-Diversion: ", "\r\n");
 ...
 
-3.23.  is_present_hf(hf_name)
+3.23. 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�
+   "From" will match with "f"
 
    Meaning of the parameters is as follows:
      * hf_name - Header field name.(long or compact form)
@@ -705,7 +712,7 @@ Note
 if (is_present_hf("From")) log(1, "From HF Present");
 ...
 
-3.24.  is_present_hf_re(hf_name_re)
+3.24. 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.
@@ -721,12 +728,12 @@ if (is_present_hf("From")) log(1, "From HF Present");
 if (is_present_hf_re("^P-")) log(1, "There are headers starting with P-\n");
 ...
 
-3.25.  append_time()
+3.25. 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:
+   '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)
@@ -745,10 +752,10 @@ if (is_present_hf_re("^P-")) log(1, "There are headers starting with P-\n");
 append_time();
 ...
 
-3.26.  append_time_to_request()
+3.26. 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:
+   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)
@@ -768,7 +775,7 @@ if(!is_present_hf("Date"))
     append_time_to_request();
 ...
 
-3.27.  is_method(name)
+3.27. 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,
@@ -805,9 +812,9 @@ if(is_method("OPTION|UPDATE"))
 }
 ...
 
-3.28.  remove_hf(hname)
+3.28. remove_hf(hname)
 
-   Remove from message all headers with name “hname�. Header matching is
+   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.
@@ -830,10 +837,10 @@ remove_hf("Contact")
 remove_hf("m")
 ...
 
-3.29.  remove_hf_re(re)
+3.29. remove_hf_re(re)
 
    Remove from message all headers with name matching regular expression
-   “re�
+   "re"
 
    Returns true if at least one header is found and removed.
 
@@ -851,16 +858,16 @@ if(remove_hf_re("^P-"))
 }
 ...
 
-3.30.  has_body(), has_body(mime)
+3.30. has_body(), has_body(mime)
 
    The function returns true if the SIP message has a body attached. The
-   checked includes also the “Content-Length� header presence and value.
+   checked 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.
+   against the "Content-Type" header.
 
    Meaning of the parameters is as follows:
-     * mime - mime to be checked against the “Content-Type� header. If not
+     * 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,
@@ -874,7 +881,7 @@ if(has_body("application/sdp"))
 }
 ...
 
-3.31.  is_audio_on_hold()
+3.31. 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.
@@ -890,7 +897,7 @@ if(is_audio_on_hold())
 }
 ...
 
-3.32.  is_privacy(privacy_type)
+3.32. 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
@@ -908,7 +915,7 @@ if(is_privacy("id"))
 }
 ...
 
-3.33.  in_list(subject, list, separator)
+3.33. 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
@@ -926,7 +933,7 @@ if (in_list("$var(subject)", "$var(list)", ",") {
 }
 ...
 
-3.34.  cmp_str(str1, str2)
+3.34. cmp_str(str1, str2)
 
    The function returns true if the two parameters matches as string case
    sensitive comparison.
@@ -942,7 +949,7 @@ if(cmp_str("$rU", "kamailio"))
 }
 ...
 
-3.35.  cmp_istr(str1, str2)
+3.35. cmp_istr(str1, str2)
 
    The function returns true if the two parameters matches as string case
    insensitive comparison.
@@ -958,7 +965,7 @@ if(cmp_istr("$rU@you", "kamailio@YOU"))
 }
 ...
 
-3.36.  starts_with(str1, str2)
+3.36. starts_with(str1, str2)
 
    The function returns true if the first string starts with the second
    string.
@@ -974,7 +981,7 @@ if (starts_with("$rU", "+358"))
 }
 ...
 
-3.37.  set_body_multipart([txt,content_type][,boundary])
+3.37. 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.
@@ -1009,7 +1016,7 @@ text
 --delimiter
 ...
 
-3.38.  append_body_part(txt,content_type[, content_disposition])
+3.38. append_body_part(txt,content_type[, content_disposition])
 
    Append a part on multipart body SIP message. Will use
    "unique-boundary-1" as boundary.
@@ -1030,8 +1037,8 @@ text
    Example 1.38. 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;handlin
-g=required");
+append_body_part("$var(b)", "application/vnd.cirpack.isdn-ext", "signal;handling
+=required");
 ...
 Will append this the body:
 ...
@@ -1043,7 +1050,44 @@ Content-Disposition: signal;handling=required
 --unique-boundary-1
 ...
 
-3.39.  remove_body_part(content_type)
+3.39. 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.39. get_body_part usage
+...
+get_body_part("application/vnd.cirpack.isdn-ext", "$var(pbody)");
+...
+
+3.40. 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.40. get_body_part_raw usage
+...
+get_body_part("application/vnd.cirpack.isdn-ext", "$var(hbody)");
+...
+
+3.41. remove_body_part(content_type)
 
    Remove a part on a multipart body SIP message.
 
@@ -1058,7 +1102,7 @@ Content-Disposition: signal;handling=required
    The core will take care of the last boundary ending "--". Detecting
    wich one is the last and fixing the others if needed.
 
-   Example 1.39. remove_body_part usage
+   Example 1.41. remove_body_part usage
 ...
 remove_body_part("application/vnd.cirpack.isdn-ext");
 ...
@@ -1080,10 +1124,10 @@ Chapter 2. Developer Guide
 
    1.1. load_textops(*import_structure)
 
-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
+     * import_structure - Pointer to the import structure - see "struct
+       textops_binds" in modules/textops/api.h