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

<chapter>
	
	<title>&adminguide;</title>
	
	<section id="overview" xreflabel="Overview">
	<title>Overview</title>
	<para>
		The module implements text based operations over the SIP message
		processed by OpenSIPS. 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, etc.
	</para>
	<para>
		Note: all SIP-aware functions like <emphasis>insert_hf</emphasis>,
		<emphasis>append_hf</emphasis> or <emphasis>codec</emphasis>
		operations have been moved to the <emphasis>sipmsgops</emphasis>
		module.
	</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:medameda@foo.bar&gt;;tag=1234
</programlisting>
	</section>
	</section>

	<section id="dependencies" xreflabel="Dependencies">
	<title>Dependencies</title>
	<section>
		<title>&osips; Modules</title>
		<para>
		The following modules must be loaded before this module:
			<itemizedlist>
			<listitem>
			<para>
				<emphasis>No dependencies on other &osips; 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 &osips; with this module loaded:
			<itemizedlist>
			<listitem>
			<para>
				<emphasis>None</emphasis>.
			</para>
			</listitem>
			</itemizedlist>
		</para>
	</section>
	</section>


	<section id="exported_functions" xreflabel="exported_functions">
	<title>Exported Functions</title>
	<section id="func_search" xreflabel="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> (string) - 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="func_search_body" xreflabel="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> (string) - 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="func_search_append" xreflabel="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> (string) - Regular expression.
			</para>
		</listitem>
		<listitem>
			<para><emphasis>txt</emphasis> (string) - 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="func_search_append_body" xreflabel="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> (string) - Regular expression.
			</para>
		</listitem>
		<listitem>
			<para><emphasis>txt</emphasis> (string) - 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="func_replace" xreflabel="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> (string) - 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("opensips", "Open SIP Server");
...
</programlisting>
		</example>
	</section>

	<section id="func_replace_body" xreflabel="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> (string) - 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("opensips", "Open SIP Server");
...
</programlisting>
		</example>
	</section>

	<section id="func_replace_all" xreflabel="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> - (string) 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("opensips", "Open SIP Server");
...
</programlisting>
		</example>
	</section>

	<section id="func_replace_body_all" xreflabel="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> (string) - 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("opensips", "Open SIP Server");
...
</programlisting>
		</example>
	</section>

	<section id="func_replace_body_atonce" xreflabel="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> (string) - 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="func_subst" xreflabel="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> (string) - 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 expression
			</para>
			<para>
			'repl' - is replacement string - may contain pseudo-variables
			</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="func_subst_uri" xreflabel="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> (string) - 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 expression
			</para>
			<para>
			'repl' - is replacement string - may contain pseudo-variables
			</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="func_subst_user" xreflabel="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> (string) - 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 expression
			</para>
			<para>
			'repl' - is replacement string - may contain pseudo-variables
			</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="func_subst_body" xreflabel="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> (string) - 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 expression
			</para>
			<para>
			'repl' - is replacement string - may contain pseudo-variables
			</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 /"))
	xlog("successfully prepared an "o" line update!\n");

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

	</section>
</chapter>

