kamailio/modules/textops/doc/textops_admin.xml

<?xml version="1.0" encoding='ISO-8859-1'?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
"http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd" [

<!-- Include general documentation entities -->
<!ENTITY % docentities SYSTEM "../../../docbook/entities.xml">
%docentities;

]>
<!-- Module User's Guide -->

<chapter>
	
	<title>&adminguide;</title>
	
	<section>
	<title>Overview</title>
	<para>
		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.
	</para>
	<section>
		<title>Known Limitations</title>
		<para>
		search ignores folded lines. For example, 
		search(<quote>(From|f):.*@foo.bar</quote>)
		doesn't match the following From header field:
		</para>
		<programlisting format="linespecific">
From: medabeda 
 &lt;sip:[email protected]&gt;;tag=1234
</programlisting>
	</section>
	</section>

	<section>
	<title>Dependencies</title>
	<section>
		<title>&kamailio; Modules</title>
		<para>
		The following modules must be loaded before this module:
			<itemizedlist>
			<listitem>
			<para>
				<emphasis>No dependencies on other &kamailio; modules</emphasis>.
			</para>
			</listitem>
			</itemizedlist>
		</para>
	</section>
	<section>
		<title>External Libraries or Applications</title>
		<para>
		The following libraries or applications must be installed before 
		running &kamailio; with this module loaded:
			<itemizedlist>
			<listitem>
			<para>
				<emphasis>None</emphasis>.
			</para>
			</listitem>
			</itemizedlist>
		</para>
	</section>
	</section>


	<section>
	<title>Functions</title>
	<section id="textops.f.search">
		<title>
		<function moreinfo="none">search(re)</function>
		</title>
		<para>
		Searches for the re in the message.
		</para>
		<para>Meaning of the parameters is as follows:</para>
		<itemizedlist>
		<listitem>
			<para><emphasis>re</emphasis> - Regular expression.
			</para>
		</listitem>
		</itemizedlist>
		<para>
		This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE, 
		FAILURE_ROUTE, BRANCH_ROUTE.
		</para>
		<example>
		<title><function>search</function> usage</title>
		<programlisting format="linespecific">
...
if ( search("[Ss][Ii][Pp]") ) { /*....*/ };
...
</programlisting>
		</example>
	</section>

	<section id="textops.f.search_body">
		<title>
		<function moreinfo="none">search_body(re)</function>
		</title>
		<para>
		Searches for the re in the body of the message.
		</para>
		<para>Meaning of the parameters is as follows:</para>
		<itemizedlist>
		<listitem>
			<para><emphasis>re</emphasis> - Regular expression.
			</para>
		</listitem>
		</itemizedlist>
		<para>
		This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE, 
		FAILURE_ROUTE, BRANCH_ROUTE.
		</para>
		<example>
		<title><function>search_body</function> usage</title>
		<programlisting format="linespecific">
...
if ( search_body("[Ss][Ii][Pp]") ) { /*....*/ };
...
</programlisting>
		</example>
	</section>

		<section id="textops.f.search_hf">
		<title>
		<function moreinfo="none">search_hf(hf, re, flags)</function>
		</title>
		<para>
		Searches for the re in the body of a header field.
		</para>
		<para>Meaning of the parameters is as follows:</para>
		<itemizedlist>
		<listitem>
			<para><emphasis>hf</emphasis> - header field name.
			</para>
		</listitem>
		<listitem>
			<para><emphasis>re</emphasis> - regular expression.
			</para>
		</listitem>
		<listitem>
			<para><emphasis>flags</emphasis> - 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.
			</para>
		</listitem>
		</itemizedlist>
		<para>
		This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE, 
		FAILURE_ROUTE, BRANCH_ROUTE.
		</para>
		<example>
		<title><function>search_body</function> usage</title>
		<programlisting format="linespecific">
...
if ( search_hf("From", ":test@", "a") ) { /*....*/ };
...
</programlisting>
		</example>
	</section>

	<section id="textops.f.search_append">
		<title>
		<function moreinfo="none">search_append(re, txt)</function>
		</title>
		<para>
		Searches for the first match of re and appends txt after it.
		</para>
		<para>Meaning of the parameters is as follows:</para>
		<itemizedlist>
		<listitem>
			<para><emphasis>re</emphasis> - Regular expression.
			</para>
		</listitem>
		<listitem>
			<para><emphasis>txt</emphasis> - String to be appended.
			</para>
		</listitem>
		</itemizedlist>
		<para>
		This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE, 
		FAILURE_ROUTE, BRANCH_ROUTE.
		</para>
		<example>
		<title><function>search_append</function> usage</title>
		<programlisting format="linespecific">
...
search_append("[Oo]pen[Ss]er", " SIP Proxy");
...
</programlisting>
		</example>
	</section>

	<section id="textops.f.search_append_body">
		<title>
		<function moreinfo="none">search_append_body(re, txt)</function>
		</title>
		<para>
		Searches for the first match of re in the body of the message
		and appends txt after it.
		</para>
		<para>Meaning of the parameters is as follows:</para>
		<itemizedlist>
		<listitem>
			<para><emphasis>re</emphasis> - Regular expression.
			</para>
		</listitem>
		<listitem>
			<para><emphasis>txt</emphasis> - String to be appended.
			</para>
		</listitem>
		</itemizedlist>
		<para>
		This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE, 
		FAILURE_ROUTE, BRANCH_ROUTE.
		</para>
		<example>
		<title><function>search_append_body</function> usage</title>
		<programlisting format="linespecific">
...
search_append_body("[Oo]pen[Ss]er", " SIP Proxy");
...
</programlisting>
		</example>
	</section>

	<section id="textops.f.replace">
		<title>
		<function moreinfo="none">replace(re, txt)</function>
		</title>
		<para>
		Replaces the first occurrence of re with txt.
		</para>
		<para>Meaning of the parameters is as follows:</para>
		<itemizedlist>
		<listitem>
			<para><emphasis>re</emphasis> - Regular expression.
			</para>
		</listitem>
		<listitem>
			<para><emphasis>txt</emphasis> - String.
			</para>
		</listitem>
		</itemizedlist>
		<para>
		This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE, 
		FAILURE_ROUTE, BRANCH_ROUTE.
		</para>
		<example>
		<title><function>replace</function> usage</title>
		<programlisting format="linespecific">
...
replace("openser", "&kamailio; SIP Proxy");
...
</programlisting>
		</example>
	</section>

	<section id="textops.f.replace_body">
		<title>
		<function moreinfo="none">replace_body(re, txt)</function>
		</title>
		<para>
		Replaces the first occurrence of re in the body of the message
		with txt.
		</para>
		<para>Meaning of the parameters is as follows:</para>
		<itemizedlist>
		<listitem>
			<para><emphasis>re</emphasis> - Regular expression.
			</para>
		</listitem>
		<listitem>
			<para><emphasis>txt</emphasis> - String.
			</para>
		</listitem>
		</itemizedlist>
		<para>
		This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE, 
		FAILURE_ROUTE, BRANCH_ROUTE.
		</para>
		<example>
		<title><function>replace_body</function> usage</title>
		<programlisting format="linespecific">
...
replace_body("openser", "&kamailio; SIP Proxy");
...
</programlisting>
		</example>
	</section>

	<section id="textops.f.replace_all">
		<title>
		<function moreinfo="none">replace_all(re, txt)</function>
		</title>
		<para>
		Replaces all occurrence of re with txt.
		</para>
		<para>Meaning of the parameters is as follows:</para>
		<itemizedlist>
		<listitem>
			<para><emphasis>re</emphasis> - Regular expression.
			</para>
		</listitem>
		<listitem>
			<para><emphasis>txt</emphasis> - String.
			</para>
		</listitem>
		</itemizedlist>
		<para>
		This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE, 
		FAILURE_ROUTE, BRANCH_ROUTE.
		</para>
		<example>
		<title><function>replace_all</function> usage</title>
		<programlisting format="linespecific">
...
replace_all("openser", "&kamailio; SIP Proxy");
...
</programlisting>
		</example>
	</section>

	<section id="textops.f.replace_body_all">
		<title>
		<function moreinfo="none">replace_body_all(re, txt)</function>
		</title>
		<para>
		Replaces all occurrence of re in the body of the message
		with txt. Matching is done on a per-line basis.
		</para>
		<para>Meaning of the parameters is as follows:</para>
		<itemizedlist>
		<listitem>
			<para><emphasis>re</emphasis> - Regular expression.
			</para>
		</listitem>
		<listitem>
			<para><emphasis>txt</emphasis> - String.
			</para>
		</listitem>
		</itemizedlist>
		<para>
		This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE, 
		FAILURE_ROUTE, BRANCH_ROUTE.
		</para>
		<example>
		<title><function>replace_body_all</function> usage</title>
		<programlisting format="linespecific">
...
replace_body_all("openser", "&kamailio; SIP Proxy");
...
</programlisting>
		</example>
	</section>

	<section id="textops.f.replace_body_atonce">
		<title>
		<function moreinfo="none">replace_body_atonce(re, txt)</function>
		</title>
		<para>
		Replaces all occurrence of re in the body of the message
		with txt. Matching is done over the whole body.
		</para>
		<para>Meaning of the parameters is as follows:</para>
		<itemizedlist>
		<listitem>
			<para><emphasis>re</emphasis> - Regular expression.
			</para>
		</listitem>
		<listitem>
			<para><emphasis>txt</emphasis> - String.
			</para>
		</listitem>
		</itemizedlist>
		<para>
		This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE, 
		FAILURE_ROUTE, BRANCH_ROUTE.
		</para>
		<example>
		<title><function>replace_body_atonce</function> usage</title>
		<programlisting format="linespecific">
...
# strip the whole body from the message:
if(has_body() &amp;&amp; replace_body_atonce("^.+$", ""))
        remove_hf("Content-Type"); 
...
</programlisting>
		</example>
	</section>

	<section id="textops.f.subst">
		<title>
		<function moreinfo="none">subst('/re/repl/flags')</function>
		</title>
		<para>
		Replaces re with repl (sed or perl like).
		</para>
		<para>Meaning of the parameters is as follows:</para>
		<itemizedlist>
		<listitem>
			<para><emphasis>'/re/repl/flags'</emphasis> - 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).
			</para>
			<para>
			're' - is regular expresion
			</para>
			<para>
			'repl' - is replacement string - may contain pseudo-varibales
			</para>
			<para>
			'flags' - substitution flags (i - ignore case, g - global)
			</para>
		</listitem>
		</itemizedlist>
		<para>
		This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE, 
		FAILURE_ROUTE, BRANCH_ROUTE.
		</para>
		<example>
		<title><function>subst</function> usage</title>
		<programlisting format="linespecific">
...
# 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') ) {};

...
</programlisting>
		</example>
	</section>

	<section id="textops.f.subst_uri">
		<title>
		<function moreinfo="none">subst_uri('/re/repl/flags')</function>
		</title>
		<para>
		Runs the re substitution on the message uri (like subst but works
		 only on the uri)
		</para>
		<para>Meaning of the parameters is as follows:</para>
		<itemizedlist>
		<listitem>
			<para><emphasis>'/re/repl/flags'</emphasis> - 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).
			</para>
			<para>
			're' - is regular expresion
			</para>
			<para>
			'repl' - is replacement string - may contain pseudo-varibales
			</para>
			<para>
			'flags' - substitution flags (i - ignore case, g - global)
			</para>
		</listitem>
		</itemizedlist>
		<para>
		This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE, 
		FAILURE_ROUTE, BRANCH_ROUTE.
		</para>
		<example>
		<title><function>subst_uri</function> usage</title>
		<programlisting format="linespecific">
...
# 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')){$

...
</programlisting>
		</example>
	</section>

	<section id="textops.f.subst_user">
		<title>
		<function moreinfo="none">subst_user('/re/repl/flags')</function>
		</title>
		<para>
		Runs the re substitution on the message uri (like subst_uri but works
		 only on the user portion of the uri)
		</para>
		<para>Meaning of the parameters is as follows:</para>
		<itemizedlist>
		<listitem>
			<para><emphasis>'/re/repl/flags'</emphasis> - 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).
			</para>
			<para>
			're' - is regular expresion
			</para>
			<para>
			'repl' - is replacement string - may contain pseudo-varibales
			</para>
			<para>
			'flags' - substitution flags (i - ignore case, g - global)
			</para>
		</listitem>
		</itemizedlist>
		<para>
		This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE, 
		FAILURE_ROUTE, BRANCH_ROUTE.
		</para>
		<example>
		<title><function>subst</function> usage</title>
		<programlisting format="linespecific">
...
# 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/')){$

...
</programlisting>
		</example>
	</section>

	<section id="textops.f.subst_body">
		<title>
		<function moreinfo="none">subst_body('/re/repl/flags')</function>
		</title>
		<para>
		Replaces re with repl (sed or perl like) in the body of the message.
		</para>
		<para>Meaning of the parameters is as follows:</para>
		<itemizedlist>
		<listitem>
			<para><emphasis>'/re/repl/flags'</emphasis> - 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).
			</para>
			<para>
			're' - is regular expresion
			</para>
			<para>
			'repl' - is replacement string - may contain pseudo-varibales
			</para>
			<para>
			'flags' - substitution flags (i - ignore case, g - global)
			</para>
		</listitem>
		</itemizedlist>
		<para>
		This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE, 
		FAILURE_ROUTE, BRANCH_ROUTE.
		</para>
		<example>
		<title><function>subst_body</function> usage</title>
		<programlisting format="linespecific">
...
if ( subst_body('/^o=(.*) /o=$fU /') ) {};

...
</programlisting>
		</example>
	</section>

	<section id="textops.f.subst_hf">
		<title>
		<function moreinfo="none">subst_hf(hf, subexp, flags)</function>
		</title>
		<para>
		Perl-like substitutions in the body of a header field.
		</para>
		<para>Meaning of the parameters is as follows:</para>
		<itemizedlist>
		<listitem>
			<para><emphasis>hf</emphasis> - header field name.
			</para>
		</listitem>
		<listitem>
			<para><emphasis>subexp</emphasis> - substitution expression
				in the same format as of the 'subst' function parameter.
			</para>
		</listitem>
		<listitem>
			<para><emphasis>flags</emphasis> - 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.
			</para>
		</listitem>
		</itemizedlist>
		<para>
		This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE, 
		FAILURE_ROUTE, BRANCH_ROUTE.
		</para>
		<example>
		<title><function>search_body</function> usage</title>
		<programlisting format="linespecific">
...
if ( subst_hf("From", "/:test@/:best@/", "a") ) { /*....*/ };
...
</programlisting>
		</example>
	</section>

	<section id="textops.f.set_body">
		<title>
		<function moreinfo="none">set_body(txt,content_type)</function>
		</title>
		<para>
		Set body to a SIP message.
		</para>
		<para>Meaning of the parameters is as follows:</para>
		<itemizedlist>
		<listitem>
			<para><emphasis>txt</emphasis> - text for the body, can include
				pseudo-variables.
			</para>
		</listitem>
		<listitem>
			<para><emphasis>content_type</emphasis> - value of Content-Type header,
				can include pseudo-variables.
			</para>
		</listitem>
		</itemizedlist>
		<para>
		This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE, 
		FAILURE_ROUTE, BRANCH_ROUTE.
		</para>
		<example>
		<title><function>set_body</function> usage</title>
		<programlisting format="linespecific">
...
set_body("test", "text/plain");
...
</programlisting>
		</example>
	</section>

	<section id="textops.f.set_reply_body">
		<title>
		<function moreinfo="none">set_reply_body(txt,content_type)</function>
		</title>
		<para>
		Set body to a SIP reply to be generated by &kamailio;.
		</para>
		<para>Meaning of the parameters is as follows:</para>
		<itemizedlist>
		<listitem>
			<para><emphasis>txt</emphasis> - text for the body, can include
				pseudo-variables.
			</para>
		</listitem>
		<listitem>
			<para><emphasis>content_type</emphasis> - value of Content-Type header,
				can include pseudo-variables.
			</para>
		</listitem>
		</itemizedlist>
		<para>
		This function can be used from REQUEST_ROUTE, FAILURE_ROUTE, BRANCH_ROUTE.
		</para>
		<example>
		<title><function>set_reply_body</function> usage</title>
		<programlisting format="linespecific">
...
set_reply_body("test", "text/plain");
...
</programlisting>
		</example>
	</section>

	<section id="textops.f.filter_body">
		<title>
		<function moreinfo="none">filter_body(content_type)</function>
		</title>
		<para>
		Filters multipart/mixed body by leaving out all other body
		parts except the first body part of given type.
		</para>
		<para>Meaning of the parameters is as follows:</para>
		<itemizedlist>
		<listitem>
			<para><emphasis>content_type</emphasis> -
				Content type to be left in the body.
			</para>
		</listitem>
		</itemizedlist>
		<para>
		This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE, 
		FAILURE_ROUTE, BRANCH_ROUTE.
		</para>
		<example>
		<title><function>filter_body</function> usage</title>
		<programlisting format="linespecific">
...
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");
    }
}
...
</programlisting>
		</example>
	</section>

	<section id="textops.f.append_to_reply">
		<title>
		<function moreinfo="none">append_to_reply(txt)</function>
		</title>
		<para>
		Append txt as header to the reply.
		</para>
		<para>Meaning of the parameters is as follows:</para>
		<itemizedlist>
		<listitem>
			<para><emphasis>txt</emphasis> - String which may contains
			pseudo-variables.
			</para>
		</listitem>
		</itemizedlist>
		<para>
		This function can be used from REQUEST_ROUTE, BRANCH_ROUTE,
		FAILURE_ROUTE, ERROR_ROUTE.
		</para>
		<example>
		<title><function>append_to_reply</function> usage</title>
		<programlisting format="linespecific">
...
append_to_reply("Foo: bar\r\n");
append_to_reply("Foo: $rm at $Ts\r\n");
...
</programlisting>
		</example>
	</section>

	<section id="textops.f.append_hf">
		<title>
		<function moreinfo="none">append_hf(txt[, hdr])</function>
		</title>
		<para>
		Appends 'txt' as header after first header field or after
		last 'hdr' header field.
		</para>
		<para>Meaning of the parameters is as follows:</para>
		<itemizedlist>
		<listitem>
			<para><emphasis>txt</emphasis> - Header field to be appended. The
			value can contain pseudo-variables which will be replaced at run
			time.
			</para>
		</listitem>
		<listitem>
			<para><emphasis>hdr</emphasis> - Header name after which the 'txt'
			is appended.
			</para>
		</listitem>
		</itemizedlist>
		<para>
		This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE, 
		FAILURE_ROUTE, BRANCH_ROUTE.
		</para>
		<example>
		<title><function>append_hf</function> usage</title>
		<programlisting format="linespecific">
...
append_hf("P-hint: VOICEMAIL\r\n");
append_hf("From-username: $fU\r\n", "Call-ID");
...
</programlisting>
		</example>
	</section>

	<section id="textops.f.insert_hf">
		<title>
		<function moreinfo="none">insert_hf(txt[, hdr])</function>
		</title>
		<para>
		Inserts 'txt' as header before the first header field or before
		first 'hdr' header field if 'hdr' is given.
		</para>
		<para>Meaning of the parameters is as follows:</para>
		<itemizedlist>
		<listitem>
			<para><emphasis>txt</emphasis> - Header field to be inserted. The
			value can contain pseudo-variables which will be replaced at run
			time.
			</para>
		</listitem>
		<listitem>
			<para><emphasis>hdr</emphasis> - Header name before which the 'txt'
			is inserted.
			</para>
		</listitem>
		</itemizedlist>
		<para>
		This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE, 
		FAILURE_ROUTE, BRANCH_ROUTE.
		</para>
		<example>
		<title><function>insert_hf</function> usage</title>
		<programlisting format="linespecific">
...
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");
...
</programlisting>
		</example>
	</section>

	<section id="textops.f.append_urihf">
		<title>
		<function moreinfo="none">append_urihf(prefix, suffix)</function>
		</title>
		<para>
		Append header field name with original <acronym>Request-URI</acronym> 
		in middle.
		</para>
		<para>Meaning of the parameters is as follows:</para>
		<itemizedlist>
		<listitem>
			<para><emphasis>prefix</emphasis> - string (usually at least 
			header field name).
			</para>
		</listitem>
		<listitem>
			<para><emphasis>suffix</emphasis> - string (usually at least 
			line terminator).
			</para>
		</listitem>
		</itemizedlist>
		<para>
		This function can be used from REQUEST_ROUTE, FAILURE_ROUTE, 
		BRANCH_ROUTE.
		</para>
		<example>
		<title><function>append_urihf</function> usage</title>
		<programlisting format="linespecific">
...
append_urihf("CC-Diversion: ", "\r\n");
...
</programlisting>
		</example>
	</section>

	<section id="textops.f.is_present_hf">
		<title>
		<function moreinfo="none">is_present_hf(hf_name)</function>
		</title>
		<para>
		Return true if a header field is present in message.
		</para>
		<note>
		<para>
			The function is also able to distinguish the compact names. For
			exmaple <quote>From</quote> will match with <quote>f</quote>
		</para>
		</note>
		<para>Meaning of the parameters is as follows:</para>
		<itemizedlist>
		<listitem>
			<para><emphasis>hf_name</emphasis> - Header field name.(long or 
			compact form)
			</para>
		</listitem>
		</itemizedlist>
		<para>
		This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE, 
		FAILURE_ROUTE, BRANCH_ROUTE.
		</para>
		<example>
		<title><function>is_present_hf</function> usage</title>
		<programlisting format="linespecific">
...
if (is_present_hf("From")) log(1, "From HF Present");
...
</programlisting>
		</example>
	</section>

	<section id="textops.f.is_present_hf_re">
		<title>
		<function moreinfo="none">is_present_hf_re(hf_name_re)</function>
		</title>
		<para>
		Return true if a header field whose name matches regular expression
		'hf_name_re' is present in message.
		</para>
		<para>Meaning of the parameters is as follows:</para>
		<itemizedlist>
		<listitem>
			<para><emphasis>hf_name_re</emphasis> - Regular expression to
				match header field name.
			</para>
		</listitem>
		</itemizedlist>
		<para>
		This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE, 
		FAILURE_ROUTE, BRANCH_ROUTE.
		</para>
		<example>
		<title><function>is_present_hf_re</function> usage</title>
		<programlisting format="linespecific">
...
if (is_present_hf_re("^P-")) log(1, "There are headers starting with P-\n");
...
</programlisting>
		</example>
	</section>

	<section id="textops.f.append_time">
		<title>
		<function moreinfo="none">append_time()</function>
		</title>
		<para>
		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: 
		<quote>Date: %a, %d %b %Y %H:%M:%S GMT</quote>, with the legend:
		<itemizedlist>
		<listitem>
			<para><emphasis>%a</emphasis> abbreviated week of day name (locale)
			</para>
		</listitem>
		<listitem>
			<para><emphasis>%d</emphasis> day of month as decimal number
			</para>
		</listitem>
		<listitem>
			<para><emphasis>%b</emphasis> abbreviated month name (locale)
			</para>
		</listitem>
		<listitem>
			<para><emphasis>%Y</emphasis> year with century
			</para>
		</listitem>
		<listitem>
			<para><emphasis>%H</emphasis> hour
			</para>
		</listitem>
		<listitem>
			<para><emphasis>%M</emphasis> minutes
			</para>
		</listitem>
		<listitem>
			<para><emphasis>%S</emphasis> seconds
			</para>
		</listitem>
		</itemizedlist>
		</para>
		<para>
		Return true if a header was succesfully appended.
		</para>
		<para>
		This function can be used from REQUEST_ROUTE, FAILURE_ROUTE, 
		BRANCH_ROUTE.
		</para>
		<example>
		<title><function>append_time</function> usage</title>
		<programlisting format="linespecific">
...
append_time();
...
</programlisting>
		</example>
	</section>

	<section id="textops.f.append_time_to_request">
		<title>
		<function moreinfo="none">append_time_to_request()</function>
		</title>
		<para>
		Adds a time header to the request. Header format is: 
		<quote>Date: %a, %d %b %Y %H:%M:%S GMT</quote>, with the legend:
		<itemizedlist>
		<listitem>
			<para><emphasis>%a</emphasis> abbreviated week of day name (locale)
			</para>
		</listitem>
		<listitem>
			<para><emphasis>%d</emphasis> day of month as decimal number
			</para>
		</listitem>
		<listitem>
			<para><emphasis>%b</emphasis> abbreviated month name (locale)
			</para>
		</listitem>
		<listitem>
			<para><emphasis>%Y</emphasis> year with century
			</para>
		</listitem>
		<listitem>
			<para><emphasis>%H</emphasis> hour
			</para>
		</listitem>
		<listitem>
			<para><emphasis>%M</emphasis> minutes
			</para>
		</listitem>
		<listitem>
			<para><emphasis>%S</emphasis> seconds
			</para>
		</listitem>
		</itemizedlist>
		</para>
		<para>
		Return true if a header was succesfully appended.
		</para>
		<para>
		This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE,
		FAILURE_ROUTE, BRANCH_ROUTE.
		</para>
		<example>
		<title><function>append_time_to_request</function> usage</title>
		<programlisting format="linespecific">
...
if(!is_present_hf("Date"))
    append_time_to_request();
...
</programlisting>
		</example>
	</section>

	<section id="textops.f.is_method">
		<title>
		<function moreinfo="none">is_method(name)</function>
		</title>
		<para>
		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.
		</para>
		<para>
		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:
		<ulink url="http://www.iana.org/assignments/sip-parameters">
			http://www.iana.org/assignments/sip-parameters</ulink>).
		</para>
		<para>
		If used for replies, the function tests the value of method field from
		CSeq header.
		</para>
		<para>Meaning of the parameters is as follows:</para>
		<itemizedlist>
		<listitem>
			<para><emphasis>name</emphasis> - SIP method name
			</para>
		</listitem>
		</itemizedlist>
		<para>
		This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE, 
		FAILURE_ROUTE, and BRANCH_ROUTE.
		</para>
		<example>
		<title><function>is_method</function> usage</title>
		<programlisting format="linespecific">
...
if(is_method("INVITE"))
{
    # process INVITEs here
}
if(is_method("OPTION|UPDATE"))
{
    # process OPTIONs and UPDATEs here
}
...
</programlisting>
		</example>
	</section>

	<section id="textops.f.remove_hf">
		<title>
		<function moreinfo="none">remove_hf(hname)</function>
		</title>
		<para>
		Remove from message all headers with name <quote>hname</quote>. 
		Header matching is case-insensitive. Matches and removes also
		the compact header forms.
		</para>
		<para>
		Returns true if at least one header is found and removed.
		</para>
		<para>Meaning of the parameters is as follows:</para>
		<itemizedlist>
		<listitem>
			<para><emphasis>hname</emphasis> - header name to be removed.
			</para>
		</listitem>
		</itemizedlist>
		<para>
		This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE, 
		FAILURE_ROUTE and BRANCH_ROUTE.
		</para>
		<example>
		<title><function>remove_hf</function> usage</title>
		<programlisting format="linespecific">
...
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")
...
</programlisting>
		</example>
	</section>

	<section id="textops.f.remove_hf_re">
		<title>
		<function moreinfo="none">remove_hf_re(re)</function>
		</title>
		<para>
			Remove from message all headers with name matching regular
			expression <quote>re</quote>
		</para>
		<para>
		Returns true if at least one header is found and removed.
		</para>
		<para>Meaning of the parameters is as follows:</para>
		<itemizedlist>
		<listitem>
			<para><emphasis>re</emphasis> - regular expression to match
				the header name to be removed.
			</para>
		</listitem>
		</itemizedlist>
		<para>
		This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE, 
		FAILURE_ROUTE and BRANCH_ROUTE.
		</para>
		<example>
		<title><function>remove_hf_re</function> usage</title>
		<programlisting format="linespecific">
...
if(remove_hf_re("^P-"))
{
    # All headers starting with "P-" removed
}
...
</programlisting>
		</example>
	</section>

	<section id="textops.f.has_body">
		<title>
		<function moreinfo="none">has_body()</function>,
		<function moreinfo="none">has_body(mime)</function>
		</title>
		<para>
		The function returns <emphasis>true</emphasis> if the SIP message
		has a body attached. The checked includes also the 
		<quote>Content-Length</quote> header presence and value.
		</para>
		<para>
		If a parameter is given, the mime described will be also checked against
		the <quote>Content-Type</quote> header.
		</para>
		<para>Meaning of the parameters is as follows:</para>
		<itemizedlist>
		<listitem>
			<para><emphasis>mime</emphasis> - mime to be checked against the 
				<quote>Content-Type</quote> header. If not present or 0, this
				check will be disabled.
			</para>
		</listitem>
		</itemizedlist>
		<para>
		This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE, 
		FAILURE_ROUTE and BRANCH_ROUTE.
		</para>
		<example>
		<title><function>has_body</function> usage</title>
		<programlisting format="linespecific">
...
if(has_body("application/sdp"))
{
    # do interesting stuff here
}
...
</programlisting>
		</example>
	</section>

	<section id="textops.f.is_audio_on_hold">
		<title>
		<function moreinfo="none">is_audio_on_hold()</function>
		</title>
		<para>
		The function returns <emphasis>true</emphasis> if the SIP message
		has a body attached and at least one audio stream in on hold.
		</para>
		<para>
		This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE, 
		FAILURE_ROUTE and BRANCH_ROUTE.
		</para>
		<example>
		<title><function>is_audio_on_hold</function> usage</title>
		<programlisting format="linespecific">
...
if(is_audio_on_hold())
{
    # do interesting stuff here
}
...
</programlisting>
		</example>
	</section>

	<section id="textops.f.is_privacy">
		<title>
		<function moreinfo="none">is_privacy(privacy_type)</function>
		</title>
		<para>
		The function returns <emphasis>true</emphasis> if 
                the SIP message has a Privacy header field that includes
                the given privacy_type among its privacy values.  See
				<ulink url="http://www.iana.org/assignments/sip-priv-values">
                http://www.iana.org/assignments/sip-priv-values</ulink>
                for possible privacy type values.
		</para>
   		<para>
		This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE, 
		FAILURE_ROUTE and BRANCH_ROUTE.
		</para>
		<example>
		<title><function>is_privacy</function> usage</title>
		<programlisting format="linespecific">
...
if(is_privacy("id"))
{
    # do interesting stuff here
}
...
</programlisting>
		</example>
	</section>

	<section id="textops.f.in_list">
		<title>
			<function moreinfo="none">in_list(subject, list, separator)</function>
		</title>
		<para>
		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.
    	        </para>
		<para>
		Function can be used from all kinds of routes.
		</para>
		<example>
			<title><function>in_list()</function> usage</title>
			<programlisting format="linespecific">
...
$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");
}
...
			</programlisting>
		</example>
	</section>

	<section id="textops.f.cmp_str">
		<title>
		<function moreinfo="none">cmp_str(str1, str2)</function>
		</title>
		<para>
		The function returns <emphasis>true</emphasis> if 
		the two parameters matches as string case sensitive comparison.
		</para>
   		<para>
		This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE, 
		FAILURE_ROUTE and BRANCH_ROUTE.
		</para>
		<example>
		<title><function>cmp_str</function> usage</title>
		<programlisting format="linespecific">
...
if(cmp_str("$rU", "kamailio"))
{
    # do interesting stuff here
}
...
</programlisting>
		</example>
	</section>

	<section id="textops.f.cmp_istr">
		<title>
		<function moreinfo="none">cmp_istr(str1, str2)</function>
		</title>
		<para>
		The function returns <emphasis>true</emphasis> if 
		the two parameters matches as string case insensitive comparison.
		</para>
   		<para>
		This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE, 
		FAILURE_ROUTE and BRANCH_ROUTE.
		</para>
		<example>
		<title><function>cmp_str</function> usage</title>
		<programlisting format="linespecific">
...
if(cmp_istr("$rU@you", "kamailio@YOU"))
{
    # do interesting stuff here
}
...
</programlisting>
		</example>
	</section>

	<section id="textops.f.starts_with">
		<title>
		<function moreinfo="none">starts_with(str1, str2)</function>
		</title>
		<para>
		The function returns <emphasis>true</emphasis> if 
		the first string starts with the second string.
		</para>
   		<para>
		This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE, 
		FAILURE_ROUTE and BRANCH_ROUTE.
		</para>
		<example>
		<title><function>starts_with</function> usage</title>
		<programlisting format="linespecific">
...
if (starts_with("$rU", "+358"))
{
    # do interesting stuff here
}
...
</programlisting>
		</example>
	</section>

	<section id="textops.f.set_body_multipart">
		<title>
		<function moreinfo="none">set_body_multipart([txt,content_type][,boundary])</function>
		</title>
		<para>
		Set multipart body to a SIP message. If called with no parameters, will convert
		present body to multipart.
		</para>
		<para>Meaning of the parameters is as follows:</para>
		<itemizedlist>
		<listitem>
			<para><emphasis>txt</emphasis> - text for the body, can include
				pseudo-variables.
			</para>
		</listitem>
		<listitem>
			<para><emphasis>content_type</emphasis> - value of Content-Type header,
				can include pseudo-variables.
			</para>
		</listitem>
		<listitem>
			<para><emphasis>boundary</emphasis> - string to use as boundary,
				can include pseudo-variables. Default: unique-boundary-1
			</para>
		</listitem>
		</itemizedlist>
		<para>
		This function can be used from REQUEST_ROUTE, FAILURE_ROUTE, BRANCH_ROUTE.
		</para>
		<para>
		The core will take care of the last boundary ending "--". Detecting wich one is
		the last and fixing the others if needed.
		</para>
		<example>
		<title><function>set_body_multipart</function> usage</title>
		<programlisting format="linespecific">
...
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
...
</programlisting>
		</example>
	</section>

	<section id="textops.f.append_body_part">
		<title>
		<function moreinfo="none">append_body_part(txt,content_type[, content_disposition])</function>
		</title>
		<para>
		Append a part on multipart body SIP message. Will use "unique-boundary-1" as boundary.
		</para>
		<para>Meaning of the parameters is as follows:</para>
		<itemizedlist>
		<listitem>
			<para><emphasis>txt</emphasis> - text for the multipart body, can include
				pseudo-variables.
			</para>
		</listitem>
		<listitem>
			<para><emphasis>content_type</emphasis> - value of Content-Type header,
				can include pseudo-variables.
			</para>
		</listitem>
		<listitem>
			<para><emphasis>content_disposition</emphasis> - value of Content-Disposition header,
				can include pseudo-variables.
			</para>
		</listitem>
		</itemizedlist>
		<para>
		This function can be used from REQUEST_ROUTE, FAILURE_ROUTE, BRANCH_ROUTE.
		</para>
		<para>
		The core will take care of the last boundary ending "--". Detecting wich one is
		the last and fixing the others if needed.
		</para>
		<example>
		<title><function>append_body_part</function> usage</title>
		<programlisting format="linespecific">
...
$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
...
</programlisting>
		</example>
	</section>

	<section id="textops.f.remove_body_part">
		<title>
		<function moreinfo="none">remove_body_part(content_type)</function>
		</title>
		<para>
		Remove a part on a multipart body SIP message.
		</para>
		<para>Meaning of the parameters is as follows:</para>
		<itemizedlist>
		<listitem>
			<para><emphasis>content_type</emphasis> - value of Content-Type header
				of the part to be removed. If more than one exists the first
				occurrence will be removed.
			</para>
		</listitem>
		</itemizedlist>
		<para>
		This function can be used from REQUEST_ROUTE, FAILURE_ROUTE, BRANCH_ROUTE.
		</para>
		<para>
		The core will take care of the last boundary ending "--". Detecting wich one is
		the last and fixing the others if needed.
		</para>
		<example>
		<title><function>remove_body_part</function> usage</title>
		<programlisting format="linespecific">
...
remove_body_part("application/vnd.cirpack.isdn-ext");
...
</programlisting>
		</example>
	</section>

	</section>
	<section>
		<title>Known Limitations</title>
		<para>
			Search functions are applied to the original request,
			i.e., they ignore all changes resulting from message
			processing in &kamailio; script.
		</para>
	</section>
</chapter>