diff --git a/modules/textops/README b/modules/textops/README index 711d9826bd4..5cfe2b2d2ab 100644 --- a/modules/textops/README +++ b/modules/textops/README @@ -23,7 +23,7 @@ Juha Heinanen - 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 ;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