%docentities; ]>

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.

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

The following modules must be loaded before this module: No dependencies on other &kamailio; modules.

The following libraries or applications must be installed before running &kamailio; with this module loaded: None.

Searches for the re in 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. ... if ( search("[Ss][Ii][Pp]") ) { /*....*/ }; ...

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. ... if ( search_body("[Ss][Ii][Pp]") ) { /*....*/ }; ...

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. ... if ( search_hf("From", ":test@", "a") ) { /*....*/ }; ...

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. ... search_append("[Oo]pen[Ss]er", " SIP Proxy"); ...

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. ... search_append_body("[Oo]pen[Ss]er", " SIP Proxy"); ...

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. ... replace("openser", "&kamailio; SIP Proxy"); ...

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. ... replace_body("openser", "&kamailio; SIP Proxy"); ...

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. ... replace_all("openser", "&kamailio; SIP Proxy"); ...

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. ... replace_body_all("openser", "&kamailio; SIP Proxy"); ...

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. ... # strip the whole body from the message: if(has_body() && replace_body_atonce("^.+$", "")) remove_hf("Content-Type"); ...

Replaces re with repl (sed or perl like). 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 expresion 'repl' - is replacement string - may contain pseudo-varibales 'flags' - substitution flags (i - ignore case, g - global) This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE, FAILURE_ROUTE, BRANCH_ROUTE. ... # 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') ) {}; ...

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 expresion 'repl' - is replacement string - may contain pseudo-varibales 'flags' - substitution flags (i - ignore case, g - global) This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE, FAILURE_ROUTE, BRANCH_ROUTE. ... # 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')){$ ...

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 expresion 'repl' - is replacement string - may contain pseudo-varibales 'flags' - substitution flags (i - ignore case, g - global) This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE, FAILURE_ROUTE, BRANCH_ROUTE. ... # 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/')){$ ...

Replaces re with repl (sed or perl like) 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 expresion 'repl' - is replacement string - may contain pseudo-varibales 'flags' - substitution flags (i - ignore case, g - global) This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE, FAILURE_ROUTE, BRANCH_ROUTE. ... if ( subst_body('/^o=(.*) /o=$fU /') ) {}; ...

Perl-like 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. ... if ( subst_hf("From", "/:test@/:best@/", "a") ) { /*....*/ }; ...

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. ... set_body("test", "text/plain"); ...

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. ... set_reply_body("test", "text/plain"); ...

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. ... 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"); } } ...

Append txt as header to the reply. Meaning of the parameters is as follows: txt - String which may contains pseudo-variables. This function can be used from REQUEST_ROUTE, BRANCH_ROUTE, FAILURE_ROUTE, ERROR_ROUTE. ... append_to_reply("Foo: bar\r\n"); append_to_reply("Foo: $rm at $Ts\r\n"); ...

Appends 'txt' as header after first header field or after last '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. ... append_hf("P-hint: VOICEMAIL\r\n"); append_hf("From-username: $fU\r\n", "Call-ID"); ...

Inserts 'txt' as header before the first header field or before first 'hdr' header field if 'hdr' is given. 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. ... 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"); ...

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. ... append_urihf("CC-Diversion: ", "\r\n"); ...

Return true if a header field is present in message. 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) This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE, FAILURE_ROUTE, BRANCH_ROUTE. ... if (is_present_hf("From")) log(1, "From HF Present"); ...

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. This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE, FAILURE_ROUTE, BRANCH_ROUTE. ... if (is_present_hf_re("^P-")) log(1, "There are headers starting with P-\n"); ...

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 succesfully appended. This function can be used from REQUEST_ROUTE, FAILURE_ROUTE, BRANCH_ROUTE. ... append_time(); ...

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 succesfully appended. This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE, FAILURE_ROUTE, BRANCH_ROUTE. ... if(!is_present_hf("Date")) append_time_to_request(); ...

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. ... if(is_method("INVITE")) { # process INVITEs here } if(is_method("OPTION|UPDATE")) { # process OPTIONs and UPDATEs here } ...

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. This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE, FAILURE_ROUTE and BRANCH_ROUTE. ... 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") ...

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 REQUEST_ROUTE, ONREPLY_ROUTE, FAILURE_ROUTE and BRANCH_ROUTE. ... if(remove_hf_re("^P-")) { # All headers starting with "P-" removed } ...

The function returns true if the SIP message has a body attached. The 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. 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. ... if(has_body("application/sdp")) { # do interesting stuff here } ...

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. ... if(is_audio_on_hold()) { # do interesting stuff here } ...

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. ... if(is_privacy("id")) { # do interesting stuff here } ...

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. ... $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"); } ...

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. ... if(cmp_str("$rU", "kamailio")) { # do interesting stuff here } ...

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. ... if(cmp_istr("$rU@you", "kamailio@YOU")) { # do interesting stuff here } ...

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. ... if (starts_with("$rU", "+358")) { # do interesting stuff here } ...

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 "--". Detecting wich one is the last and fixing the others if needed. ... set_body_multipart("test", "text/plain", "delimiter"); ... Will produce: ... Content-Type: multipart/mixed;boundary="delimiter" Mime-Version: 1.0 --delimiter Content-Type: text/plain text --delimiter ...

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 "--". Detecting wich one is the last and fixing the others if needed. ... $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"); ... Will append this 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 ...

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 "--". Detecting wich one is the last and fixing the others if needed. ... remove_body_part("application/vnd.cirpack.isdn-ext"); ...

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