sipmsgops_admin.xml

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

<chapter>

	<title>&adminguide;</title>

	<section id="overview" xreflabel="Overview">
	<title>Overview</title>
	<para>
		The module implements SIP based operations over the messages
		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 SIP level, e.g., inserting new headers or deleting them,
		check for method type, etc.
	</para>
	</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_append_to_reply" xreflabel="append_to_reply()">
		<title>
		<function moreinfo="none">append_to_reply(txt)</function>
		</title>
		<para>
		Append 'txt' as header to all replies that will be generated by
		OpenSIPS for this request.
		</para>
		<para>Meaning of the parameters is as follows:</para>
		<itemizedlist>
		<listitem>
			<para><emphasis>txt (string)</emphasis> - SIP header field,
				value and CRLF marker.
			</para>
		</listitem>
		</itemizedlist>
		<para>
		This function can be used from REQUEST_ROUTE, FAILURE_ROUTE,
		BRANCH_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="func_append_hf" xreflabel="append_hf()">
		<title>
		<function moreinfo="none">append_hf(txt[, hdr_anchor])</function>
		</title>
		<para>
			Appends 'txt' as header after the last header field.  If
			'hdr_anchor' is given, 'txt' will be appended after the first
			occurrence of 'hdr_anchor' instead.
		</para>
		<para>Meaning of the parameters is as follows:</para>
		<itemizedlist>
		<listitem>
			<para><emphasis>txt (string)</emphasis> - Header field to be appended.
			</para>
		</listitem>
		<listitem>
			<para><emphasis>hdr_anchor (string, optional)</emphasis> - Header name
				after which the 'txt' is appended.
			</para>
		</listitem>
		</itemizedlist>
		<para>
		Note: Headers which are added in main route cannot be removed in further routes
		(e.g. failure routes). So, the idea is not to add there any headers that you
		might want to remove later. To add headers temporarily, use the branch route
		because the changes you do there are per-branch.
		</para>
		<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");
append_hf("From-username: $fU\r\n", "Call-ID");
...
</programlisting>
		</example>
	</section>

	<section id="func_insert_hf" xreflabel="insert_hf()">
		<title>
		<function moreinfo="none">insert_hf(txt)</function>
		</title>
		<para>
		Inserts 'txt' as header before the first header field.
		</para>
		<para>Meaning of the parameters is as follows:</para>
		<itemizedlist>
		<listitem>
			<para><emphasis>txt (string)</emphasis> - Header field to be 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");
...
</programlisting>
		</example>
	</section>


	<section id="func_insert_hf_2" xreflabel="insert_hf()">
		<title>
		<function moreinfo="none">insert_hf(txt, hdr)</function>
		</title>
		<para>
		Inserts 'txt' as header before first 'hdr' header field.
		</para>
		<para>Meaning of the parameters is as follows:</para>
		<itemizedlist>
		<listitem>
			<para><emphasis>txt (string)</emphasis> - Header field to be inserted.
			</para>
		</listitem>
		<listitem>
			<para><emphasis>hdr (string, optional)</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", "Call-ID");
insert_hf("To-username: $tU\r\n", "Call-ID");
...
</programlisting>
		</example>
	</section>

	<section id="func_append_urihf" xreflabel="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="func_is_present_hf" xreflabel="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 (string)</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="func_append_time" xreflabel="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 successfully 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="func_is_method" xreflabel="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 &osips; with ID (invite, cancel, ack,
		bye, options, info, update, register, message, subscribe, notify,
		refer, prack, publish; for more see:
		<ulink url="https://www.iana.org/assignments/sip-parameters">
			https://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 (string)</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="func_remove_hf" xreflabel="remove_hf()">
		<title>
		<function moreinfo="none">remove_hf(hname)</function>
		</title>
		<para>
		Remove from message all headers with name <quote>hname</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>hname (string)</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
}
...
</programlisting>
		</example>
	</section>


	<section id="func_remove_hf_re" xreflabel="remove_hf_re()">
		<title>
		<function moreinfo="none">remove_hf_re(hname_expr)</function>
		</title>
		<para>
			Remove from message all headers matching the
			<quote>hname_expr</quote> POSIX regular expression.
		</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_expr (string)</emphasis> - regular expression.
			</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">
...
remove_hf_re("^X-g.+[0-9]");
...
</programlisting>
		</example>
	</section>


	<section id="func_remove_hf_glob" xreflabel="remove_hf_glob()">
		<title>
		<function moreinfo="none">remove_hf_glob(hname_pattern)</function>
		</title>
		<para>
			Remove from message all headers matching the
			<quote>hname_pattern</quote> glob pattern.
		</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_pattern (string)</emphasis> - glob pattern
			</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_glob</function> usage</title>
		<programlisting format="linespecific">
...
# removes X-Billing-Account, X-Billing-Price, X-Billing-rateplan, etc
remove_hf_glob("X-Billing*");
...
</programlisting>
		</example>
	</section>



	<section id="func_has_totag" xreflabel="has_totag()">
		<title>
		<function moreinfo="none">has_totag()</function>
		</title>
		<para>
		Check if To header field uri contains tag parameter.
		</para>
		<para>
		This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE,
		FAILURE_ROUTE, BRANCH_ROUTE and LOCAL_ROUTE.
		</para>
		<example>
		<title><function>has_totag</function> usage</title>
		<programlisting format="linespecific">
...
if (has_totag()) {
	...
};
...
</programlisting>
		</example>
	</section>
	<section id="func_ruri_has_param" xreflabel="ruri_has_param()">
		<title>
		<function moreinfo="none">ruri_has_param(param[,value])</function>
		</title>
		<para>
		Find if Request URI has a given parameter. If no value is given,
		the function will look for the paramter with no value, oherwise it
		will search for the parameter with the matching value.
		</para>
		<para>Meaning of the parameters is as follows:</para>
		<itemizedlist>
		<listitem>
			<para><emphasis>param (string)</emphasis> - parameter name to look for.
			</para>
		</listitem>
		<listitem>
			<para><emphasis>value (string, optional)</emphasis> - parameter value to match.
			</para>
		</listitem>
		</itemizedlist>
		<para>
		This function can be used from REQUEST_ROUTE,
		FAILURE_ROUTE, BRANCH_ROUTE and LOCAL_ROUTE.
		</para>
		<example>
		<title><function>ruri_has_param</function> usage</title>
		<programlisting format="linespecific">
...
if (ruri_has_param("user","phone")) {
	...
};
...
</programlisting>
		</example>
	</section>

	<section id="func_ruri_add_param" xreflabel="ruri_add_param()">
		<title>
		<function moreinfo="none">ruri_add_param(param)</function>
		</title>
		<para>
		Add to RURI an URI parameter formated as "name=value".
		</para>
		<para>Meaning of the parameters is as follows:</para>
		<itemizedlist>
		<listitem>
			<para><emphasis>param (string)</emphasis> - parameter to be appended in
			<quote>name=value</quote> format.
			</para>
		</listitem>
		</itemizedlist>
		<para>
		This function can be used from REQUEST_ROUTE,
		FAILURE_ROUTE, BRANCH_ROUTE and LOCAL_ROUTE.
		</para>
		<example>
		<title><function>ruri_add_param</function> usage</title>
		<programlisting format="linespecific">
...
ruri_add_param("nat=yes");
...
</programlisting>
		</example>
	</section>

	<section id="func_ruri_del_param" xreflabel="ruri_del_param()">
		<title>
		<function moreinfo="none">ruri_del_param(param)</function>
		</title>
		<para>
		Delete a parameter from the RURI being given the key(key=value);
		</para>
		<para>Meaning of the parameters is as follows:</para>
		<itemizedlist>
		<listitem>
			<para><emphasis>param (string)</emphasis> - key of the parameter to be removed/
			</para>
		</listitem>
		</itemizedlist>
		<para>
		This function can be used from REQUEST_ROUTE,
		FAILURE_ROUTE, BRANCH_ROUTE and LOCAL_ROUTE.
		</para>
		<example>
		<title><function>ruri_del_param</function> usage</title>
		<programlisting format="linespecific">
...
ruri_del_param("user");
...
</programlisting>
		</example>
	</section>

	<section id="func_ruri_tel2sip" xreflabel="ruri_tel2sip()">
		<title>
		<function moreinfo="none">ruri_tel2sip()</function>
		</title>
		<para>
		Converts RURI, if it is tel URI, to SIP URI.  Returns true, only if
		conversion succeeded or if no conversion was needed (like RURI
		was not tel URI.
		</para>
		<para>
		This function can be used from REQUEST_ROUTE,
		FAILURE_ROUTE, BRANCH_ROUTE and LOCAL_ROUTE.
		</para>
		<example>
		<title><function>ruri_tel2sip</function> usage</title>
		<programlisting format="linespecific">
...
ruri_tel2sip();
...
</programlisting>
		</example>
	</section>

	<section id="func_is_uri_user_e164" xreflabel="is_uri_user_e164()">
		<title>
		<function moreinfo="none">is_uri_user_e164(uri)</function>
		</title>
		<para>
		Checks if the username part of the given URI is an E164 number.
		</para>
		<para>Meaning of the parameters is as follows:</para>
		<itemizedlist>
		<listitem>
			<para><emphasis>uri (string)</emphasis> - a SIP URI
			</para>
		</listitem>
		</itemizedlist>
		<para>
		This function can be used from REQUEST_ROUTE and FAILURE_ROUTE.
		</para>
		<example>
		<title><function>is_uri_user_e164</function> usage</title>
		<programlisting format="linespecific">
...
if (is_uri_user_e164($fu)) {  # Check From header URI user part
   ...
}
if (is_uri_user_e164($avp(uri)) {
   # Check user part of URI stored in avp uri
   ...
};
...
</programlisting>
		</example>
	</section>




	<section id="func_has_body_part" xreflabel="has_body_part()">
		<title>
		<function moreinfo="none">has_body_part([mime])</function>
		</title>
		<para>
		The function returns <emphasis>true</emphasis> if the SIP message
		has any body part with the given MIME. If there is no MIME given,
		it will return true if at least one body part is found (with any MIME).
		</para>
		<para>
		This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE,
		FAILURE_ROUTE and BRANCH_ROUTE.
		</para>
		<example>
		<title><function>has_body_part</function> usage</title>
		<programlisting format="linespecific">
...
if(has_body_part("application/sdp"))
{
    # do interesting stuff here
}
...
</programlisting>
		</example>
	</section>

	<section id="func_is_audio_on_hold" xreflabel="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 an SDP body attached and at least one audio stream in on hold.
		The return code of the function indicates the detected hold type:
		<itemizedlist>
		<listitem>
			<para><emphasis>1</emphasis> - RFC2543 hold type:
			null connection IP detected
			</para>
		</listitem>
		<listitem>
			<para><emphasis>2</emphasis> - RFC3264 hold type:
			inactive or sendonly attributes detected
			</para>
		</listitem>
		</itemizedlist>
		</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())
{
    switch ($rc) {
    case 1:
        # RFC2543 hold type
    	# do interesting stuff here
        break;
    case 2:
        # RFC3264 hold type
    	# do interesting stuff here
        break;
}
...
</programlisting>
		</example>
	</section>

	<section id="func_is_privacy" xreflabel="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="https://www.iana.org/assignments/sip-parameters/sip-parameters.xhtml#sip-parameters-8">
                https://www.iana.org/assignments/sip-parameters/sip-parameters.xhtml#sip-parameters-8</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="func_remove_body_part" xreflabel="remove_body_part()">
		<title>
		<function moreinfo="none">remove_body_part([mime[, revert]])</function>
		</title>

		<para>
		Removes from the message body all the body parts with the given mime.
		The necessary corrections over the Content-Type and Content-Length
		headers are automatically done.
		</para>
		<para>
		If a MIME type is given, it will delete only the body parts with
		that mime. If no MIME given, all the parts (entire body) will be
		removed.
		</para>
		<para>Meaning of the parameters is as follows:</para>
		<itemizedlist>
		<listitem>
			<para><emphasis>mime (string, optional)</emphasis> - MIME type to
				be checked against the body parts; If not given, all parts
				are to remvoed;
			</para>
		</listitem>
		<listitem>
			<para><emphasis>revert (string, optional)</emphasis> - useful only
				if a MIME was specified. If "revert" string is given here, the
				function will delete all body parts but the ones with the given MIME.
			</para>
		</listitem>
		</itemizedlist>

		<para>
		This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE,
		FAILURE_ROUTE, BRANCH_ROUTE and LOCAL_ROUTE.
		</para>
		<example>
		<title><function>remove_body_part()</function> usage</title>
		<programlisting format="linespecific">
...
# delete entire body message (all parts)
remove_body_part();
# delete all body parts with mime "application/isup"
remove_body_part("application/isup");
# delete all body parts but keep the the ones with  "application/sdp"
remove_body_part("application/sdp","revert")
...
</programlisting>
		</example>
	</section>

	<section id="func_add_body_part" xreflabel="add_body_part()">
		<title>
		<function moreinfo="none">add_body_part(body, mime[, headers])</function>
		</title>
		<para>
		This function can be used to add a new body part to the message body.
		If another part already exist, body of the message will be converted
		to a multi-part body automatically.
		</para>
		<para>Meaning of the parameters is as follows:</para>
		<itemizedlist>
		<listitem>
			<para><emphasis>body (string)</emphasis> - the content of the body part
			to be added
			</para>
		</listitem>
		<listitem>
			<para><emphasis>mime (string)</emphasis> - the mime string for the body
			part to be added
			</para>
		</listitem>
		<listitem>
			<para><emphasis>headers (string, optional)</emphasis> - optional list of SIP headers
			(fully defined, including the header separator) to be pushed into
			this part next to the <emphasis>Content-Type</emphasis> header.
			</para>
		</listitem>

		</itemizedlist>

		<para>
		This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE,
		FAILURE_ROUTE, BRANCH_ROUTE and LOCAL_ROUTE.
		</para>
		<example>
		<title><function>add_body_part</function> usage</title>
		<programlisting format="linespecific">
...
add_body_part("Hello World!", "text/plain");
...
</programlisting>
		</example>
	</section>


	<section id="func_get_updated_body_part" xreflabel="get_updated_body_part()">
		<title>
		<function moreinfo="none">get_updated_body_part( [mime], variable)</function>
		</title>
		<para>
		This function returns into a variable the regenerated body part,
		meaning the body part updated with all the changes done so far by 
		OpenSIPS. This is helpful if you want to do a sequance of operations
		over the body parts and some operations require to have all the
		previous changes applied (like first doing some codec related changes
		and later to rtpengine insertion).
		</para>
		<para>
		NOTE: the actual SIP message will not be affected by this operation!
		</para>
		<para>Meaning of the parameters is as follows:</para>
		<itemizedlist>
		<listitem>
			<para><emphasis>mime (string)</emphasis> - the mime string for
			the body to be regenerated and returned. If missing, the whole
			body (with all its parts) will be regenerated.
			</para>
		</listitem>
		<listitem>
			<para><emphasis>variable</emphasis> - a variable to be used to 
			return the regenerated body part (as text).
			</para>
		</listitem>
		</itemizedlist>

		<para>
		This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE,
		FAILURE_ROUTE, BRANCH_ROUTE and LOCAL_ROUTE.
		</para>
		<example>
		<title><function>get_updated_body_part</function> usage</title>
		<programlisting format="linespecific">
...
	codec_delete_re("PCMA|PCMU");

	get_updated_body_part( "application/sdp", $var(new_sdp));

	xlog("------updated SDP is ----\n$var(new_sdp)\n-----------\n");
	exit;
...
</programlisting>
		</example>
	</section>


	<section id="func_sipmsg_validate" xreflabel="sipmsg_validate()">
		<title>
		<function moreinfo="none">sipmsg_validate([flags[, result_pvar]])</function>
		</title>
		<para>
		The function returns <emphasis>true</emphasis> if the SIP message
		is properly built according to SIP RFC3261. It verifies if the
		mandatory headers for each request/reply and can also check the format
		of the headers body.
		</para>
		<para>The flags parameter received is optional and can be composed
			with the following values:
			<itemizedlist>
				<listitem><para><emphasis>'s'</emphasis> - checks the
						integrity of the SDP body, if it exists
				</para></listitem>
				<listitem><para><emphasis>'h'</emphasis> - checks the format
						and integrity of each header body.
				</para></listitem>
				<listitem><para><emphasis>'m'</emphasis> - don't check the
						Max-Forwards header.
				</para></listitem>
				<listitem><para><emphasis>'r'</emphasis> - checks the R-URI
						and whether the domain contains valid characters.
				</para></listitem>
				<listitem><para><emphasis>'f'</emphasis> - checks the URI of the 'From' field
						and whether the domain contains valid characters.
				</para></listitem>
				<listitem><para><emphasis>'t'</emphasis> - checks the URI of the 'To' field
						and whether the domain contains valid characters.
				</para></listitem>
				<listitem><para><emphasis>'c'</emphasis> - checks the URI of the 'Contact' field.
				</para></listitem>
			</itemizedlist>
		</para>
		<para>The result_pvar parameter sets resulting pvar with text error reason in case of
			negative result ( easy for logging or propagating the rejection reason back to the
			bogus UA )
		</para>
		<para>This function can return the following codes:
			<itemizedlist>
				<listitem><para><emphasis>1</emphasis> - the message is
						RFC3261 compliant and has been successfully validated.
				</para></listitem>
				<listitem><para><emphasis>-1</emphasis> - No SIP message
				</para></listitem>
				<listitem><para><emphasis>-2</emphasis> - Header Parsing error
				</para></listitem>
				<listitem><para><emphasis>-3</emphasis> - No Call-ID header
				</para></listitem>
				<listitem><para><emphasis>-4</emphasis> - No Content-Length header for transports that require it ( eg. TCP )
				</para></listitem>
				<listitem><para><emphasis>-5</emphasis> - Invalid Content-Length, other from the size of the actual body
				</para></listitem>
				<listitem><para><emphasis>-6</emphasis> - SDP body parsing error.
				</para></listitem>
				<listitem><para><emphasis>-7</emphasis> - No Cseq header.
				</para></listitem>
				<listitem><para><emphasis>-8</emphasis> - No From header.
				</para></listitem>
				<listitem><para><emphasis>-9</emphasis> - No To header.
				</para></listitem>
				<listitem><para><emphasis>-10</emphasis> - No Via header.
				</para></listitem>
				<listitem><para><emphasis>-11</emphasis> - Request URI parse error.
				</para></listitem>
				<listitem><para><emphasis>-12</emphasis> - Bad hostname in R-URI.
				</para></listitem>
				<listitem><para><emphasis>-13</emphasis> - No Max-Forwards header.
				</para></listitem>
				<listitem><para><emphasis>-14</emphasis> - No Contact header.
				</para></listitem>
				<listitem><para><emphasis>-15</emphasis> - Path user for non-Register request.
				</para></listitem>
				<listitem><para><emphasis>-16</emphasis> - No allow header in 405 reply.
				</para></listitem>
				<listitem><para><emphasis>-17</emphasis> - No Min-Expire header in 423 reply.
				</para></listitem>
				<listitem><para><emphasis>-18</emphasis> - No Proxy-Authorize header in 407 reply.
				</para></listitem>
				<listitem><para><emphasis>-19</emphasis> - No Unsupported header in 420 reply.
				</para></listitem>
				<listitem><para><emphasis>-20</emphasis> - No WWW-Authorize header in 401 reply.
				</para></listitem>
				<listitem><para><emphasis>-21</emphasis> - No Content-Type header
				</para></listitem>
				<listitem><para><emphasis>-22</emphasis> - To header parse error
				</para></listitem>
				<listitem><para><emphasis>-23</emphasis> - Bad hostname in To header
				</para></listitem>
				<listitem><para><emphasis>-24</emphasis> - From header parse error
				</para></listitem>
				<listitem><para><emphasis>-25</emphasis> - Bad hostname in From header
				</para></listitem>
				<listitem><para><emphasis>-26</emphasis> - Contact header parse error
				</para></listitem>
				<listitem><para><emphasis>-27</emphasis> - Bad URI username
				</para></listitem>
				<listitem><para><emphasis>-28</emphasis> - Bad From URI username
				</para></listitem>
				<listitem><para><emphasis>-29</emphasis> - Bad To URI username
				</para></listitem>
				<listitem><para><emphasis>-255</emphasis> - undefined errors.
				</para></listitem>
			</itemizedlist>
		</para>
		<para>
		This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE,
		FAILURE_ROUTE and BRANCH_ROUTE.
		</para>
		<example>
		<title><function>sipmsg_validate</function> usage</title>
		<programlisting format="linespecific">
...
if(!sipmsg_validate())
{
	send_reply(400, "Bad Request");
	exit;
}
...

...
# checks also the SDP and headers body
if(!sipmsg_validate("sh", $var(err_reason)))
{
	send_reply(400, "Bad Request/Body");
	exit;
}
...
</programlisting>
		</example>
	</section>



	<section id="func_codec_exists" xreflabel="codec_exists()">
		<title>
		<function moreinfo="none">codec_exists (name[, clock])</function>
		</title>
		<para>
		This function can be used to verify if a codec exists inside an
		sdp payload. It will search for the codec inside all streams from all
		sdp sessions. If it is found anywhere it will return TRUE otherwise
		it will	return FALSE.
		</para>
		<para>Parameters:</para>
		<itemizedlist>
			<listitem><para>
				<emphasis>name</emphasis> (string) - Parameter is CASE INSENSITIVE.
			</para></listitem>
			<listitem><para>
				<emphasis>clock</emphasis> (string, optional) - if not supplied
				any clockrate will match. Parameter is CASE INSENSITIVE.
			</para></listitem>
		</itemizedlist>
   		<para>
		This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE,
		FAILURE_ROUTE, BRANCH_ROUTE and LOCAL_ROUTE.
		</para>
		<example>
		<title><function>codec_exists</function> usage</title>
		<programlisting format="linespecific">
...
codec_exists("speex");
or
codec_exists("GSM", "8000");
...
</programlisting>
		</example>
	</section>

	<section id="func_codec_delete" xreflabel="codec_delete()">
		<title>
		<function moreinfo="none">codec_delete(name[, clock])</function>
		</title>
		<para>
		This function can be used to delete a codec from inside an
		sdp payload. It will search for the codec inside all streams from all
		sdp sessions. If it is found anywhere it will be deleted from the
		mapping ("a=...") and from the list of indexes ("m=...").
		Returns TRUE if any deletion occurred otherwise
		it will	return FALSE.
		</para>
		<itemizedlist>
			<listitem><para>
				<emphasis>name</emphasis> (string) - Parameter is CASE INSENSITIVE.
			</para></listitem>
			<listitem><para>
				<emphasis>clock</emphasis> (string, optional) - if not supplied
				any clockrate will match and all will be deleted. Parameter is CASE INSENSITIVE.
			</para></listitem>
		</itemizedlist>
   		<para>
		This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE,
		FAILURE_ROUTE, BRANCH_ROUTE and LOCAL_ROUTE.
		</para>
		<example>
		<title><function>codec_delete</function> usage</title>
		<programlisting format="linespecific">
...
codec_delete("speex");
or
codec_delete("GSM", "8000");
...
</programlisting>
		</example>
	</section>

	<section id="func_codec_move_up" xreflabel="codec_move_up()">
		<title>
		<function moreinfo="none">codec_move_up(name[, clock])</function>
		</title>
		<para>
		This function can be used to move a codec up in the list
		of indexes ("m=..."). It will search for the codec inside all streams from all
		sdp sessions. If it is found anywhere it will be moved to the top
		of the index list. Returns TRUE if any moves occurred otherwise
		it will	return FALSE.
		</para>
		<itemizedlist>
			<listitem><para>
				<emphasis>name</emphasis> (string) - parameter is CASE INSENSITIVE.
			</para></listitem>
			<listitem><para>
				<emphasis>clock</emphasis> (string, optional) - if not supplied
				any clockrate will match and all codecs
				will be moved to the front while preserving their original ordering.
				Parameter is CASE INSENSITIVE.
			</para></listitem>
		</itemizedlist>
   		<para>
		This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE,
		FAILURE_ROUTE, BRANCH_ROUTE and LOCAL_ROUTE.
		</para>
		<example>
		<title><function>codec_move_up</function> usage</title>
		<programlisting format="linespecific">
...
codec_move_up("speex");
or
codec_move_up("GSM", "8000");
...
</programlisting>
		</example>
	</section>

		<section id="func_codec_move_down" xreflabel="codec_move_down()">
		<title>
		<function moreinfo="none">codec_move_down(name[, clock])</function>
		</title>
		<para>
		This function can be used to move a codec down in the list
		of indexes ("m=..."). It will search for the codec inside all streams from all
		sdp sessions. If it is found anywhere it will be moved to the back
		of the index list. Returns TRUE if any moves occurred otherwise
		it will	return FALSE. The second parameter is optional,
		if it is not supplied any clockrate will match and all codecs
		will be moved to the back while preserving their original ordering.
		Parameters are CASE INSENSITIVE.
		</para>
		<itemizedlist>
			<listitem><para>
				<emphasis>name</emphasis> (string) - parameter is CASE INSENSITIVE.
			</para></listitem>
			<listitem><para>
				<emphasis>clock</emphasis> (string, optional) - if not supplied
				any clockrate will match and all codecs
				will be moved to the back while preserving their original ordering.
				Parameter is CASE INSENSITIVE.
			</para></listitem>
		</itemizedlist>
   		<para>
		This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE,
		FAILURE_ROUTE, BRANCH_ROUTE and LOCAL_ROUTE.
		</para>
		<example>
		<title><function>codec_move_down</function> usage</title>
		<programlisting format="linespecific">
...
codec_move_down("speex");
or
codec_move_down("GSM", "8000");
...
</programlisting>
		</example>

		<example>
		<title><function>codec_move_down</function> usage</title>
		<programlisting format="linespecific">
...
/*
  This example will move speex with 8000 codec to the back of the list,
  then it will erase GSM with 8000 clock, and then it will bring all
  speex codecs to the front of the list. Speex/8000 will be behind any
  other speex.
*/
codec_move_down("speex", "8000");
codec_delete("GSM", "8000");
codec_move_up("speex");
...
</programlisting>
		</example>
	</section>


	<section id="func_codec_exists_re" xreflabel="codec_exists_re()">
		<title>
		<function moreinfo="none">codec_exists_re ( regexp )</function>
		</title>
		<para>
		This function has the same effect as codec_exists ( without
		the clock parameter ) the only
		difference is that it takes a POSIX regular expression
		as a parameter.
		</para>
   		<para>
		This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE,
		FAILURE_ROUTE, BRANCH_ROUTE and LOCAL_ROUTE.
		</para>
		<example>
		<title><function>codec_exists_re</function> usage</title>
		<programlisting format="linespecific">
...
codec_exists_re("sp[a-z]*");
...
</programlisting>
		</example>
	</section>

	<section id="func_codec_delete_re" xreflabel="codec_delete_re()">
		<title>
		<function moreinfo="none">codec_delete_re ( regexp )</function>
		</title>
		<para>
		This function has the same effect as codec_delete ( without
		the clock parameter ) the only
		difference is that it takes a POSIX regular expression
		as a parameter.
		</para>
   		<para>
		This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE,
		FAILURE_ROUTE, BRANCH_ROUTE and LOCAL_ROUTE.
		</para>
		<example>
		<title><function>codec_delete_re</function> usage</title>
		<programlisting format="linespecific">
...
codec_delete_re("PCMA|PCMU");
...

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

        <section id="func_codec_delete_except_re" xreflabel="codec_delete_except_re()">
		<title>
		<function moreinfo="none">codec_delete_except_re ( regexp )</function>
		</title>
		<para>
		This function deletes all the codecs except those specified
                by the regular expression.
		</para>
   		<para>
		This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE,
		FAILURE_ROUTE, BRANCH_ROUTE and LOCAL_ROUTE.
		</para>
		<example>
		<title><function>codec_delete_except_re</function> usage</title>
		<programlisting format="linespecific">
...
codec_delete_except_re("PCMA|PCMU");#will delete all codecs except PCMA and PCMU
...

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

	<section id="func_codec_move_up_re" xreflabel="codec_move_up_re()">
		<title>
		<function moreinfo="none">codec_move_up_re ( regexp )</function>
		</title>
		<para>
		This function has the same effect as codec_move_up ( without
		the clock parameter ) the only
		difference is that it takes a POSIX regular expression
		as a parameter.
		</para>
   		<para>
		This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE,
		FAILURE_ROUTE, BRANCH_ROUTE and LOCAL_ROUTE.
		</para>
		<example>
		<title><function>codec_move_up_re</function> usage</title>
		<programlisting format="linespecific">
...
codec_move_up_re("sp[a-z]*");
...
</programlisting>
		</example>
	</section>

		<section id="func_codec_move_down_re" xreflabel="codec_move_down_re()">
		<title>
		<function moreinfo="none">codec_move_down_re ( regexp )</function>
		</title>
		<para>
		This function has the same effect as codec_move_down ( without
		the clock parameter ) the only
		difference is that it takes a POSIX regular expression
		as a parameter.
		</para>
   		<para>
		This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE,
		FAILURE_ROUTE, BRANCH_ROUTE and LOCAL_ROUTE.
		</para>
		<example>
		<title><function>codec_move_down_re</function> usage</title>
		<programlisting format="linespecific">
...
codec_move_down_re("sp[a-z]*");
...
</programlisting>
		</example>

		<example>
		<title><function>codec_move_down</function> usage</title>
		<programlisting format="linespecific">
...
/*
  This example will move speex with 8000 codec to the back of the list,
  then it will erase GSM with 8000 clock, and then it will bring all
  speex codecs to the front of the list. Speex/8000 will be behind any
  other speex.
*/
codec_move_down("speex","8000");
codec_delete("GSM","8000");
codec_move_up("speex");
...
</programlisting>
		</example>

	</section>


    <section id="change_reply_status">
	<title>
	    <function>change_reply_status(code, reason)</function>
	</title>
	<para>
		Intercept a SIP reply (in any onreply_route) and change its status code
		and reason phrase prior to propogating it.
	</para>
	<para>Meaning of the parameters is as follows:</para>
	<itemizedlist>
	    <listitem>
		<para><emphasis>code (int)</emphasis> - Status code.
		</para>
	    </listitem>
	    <listitem>
		<para><emphasis>reason (string)</emphasis> - Reason phrase.
		</para>
	    </listitem>
	</itemizedlist>
   		<para>
		This function can be used from ONREPLY_ROUTE.
		</para>
	<example>
	    <title><function>change_reply_status</function> usage</title>
	    <programlisting>
...
onreply_route {
    if ($rs == "603") {
        change_reply_status(404, "Not Found");
        exit;
    }
}
...
	    </programlisting>
	</example>
    </section>

	<section id="func_stream_exists" xreflabel="stream_exists()">
		<title>
		<function moreinfo="none">stream_exists(regexp[,regexp2])</function>
		</title>
		<para>
		This function can be used to verify if a stream exists inside an
		sdp payload. It will search for the stream inside all sdp sessions.
		If it is found anywhere it will return TRUE otherwise
		it will return FALSE.
		</para>
		<para>Meaning of the parameters is as follows:</para>
		<itemizedlist>
		<listitem>
		<para><emphasis>regexp</emphasis> - a POSIX regular expression
		to match the stream media name.
		</para>
		</listitem>
		<listitem>
		<para><emphasis>regexp2</emphasis> - an optional POSIX regular 
		expression to match the stream transport name.
		</para>
		</listitem>
		</itemizedlist>
		<para>
		This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE,
		FAILURE_ROUTE, BRANCH_ROUTE and LOCAL_ROUTE.
		</para>
		<example>
		<title><function>stream_exists</function> usage</title>
		<programlisting format="linespecific">
...
# check for FAX
stream_exists("image");
...
stream_exists("audio","SAVP");
...
</programlisting>
		</example>
	</section>

	<section id="func_stream_delete" xreflabel="stream_delete()">
		<title>
		<function moreinfo="none">stream_delete(regexp[,regexp2])</function>
		</title>
		<para>
		This function can be used to delete a whole stream from inside an
		sdp payload. It will search for the stream inside all sdp sessions.
		If it is found anywhere it will be deleted along with all attributes
		Returns TRUE if any deletion occurred otherwise
		it will return FALSE.
		</para>
		<para>Meaning of the parameters is as follows:</para>
		<itemizedlist>
		<listitem>
		<para><emphasis>regexp</emphasis> - a POSIX regular expression
		to match the stream media name.
		</para>
		</listitem>
		<listitem>
		<para><emphasis>regexp2</emphasis> - an optional POSIX regular 
		expression to match the stream transport name.
		</para>
		</listitem>
		</itemizedlist>
		<para>
		This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE,
		FAILURE_ROUTE, BRANCH_ROUTE and LOCAL_ROUTE.
		</para>
		<example>
		<title><function>stream_delete</function> usage</title>
		<programlisting format="linespecific">
...
# prevent usage of video
stream_delete("video");
...
</programlisting>
		</example>
	</section>

	<section id="func_list_hdr_has_option" xreflabel="list_hdr_has_option()">
		<title>
		<function moreinfo="none">list_hdr_has_option(hdr_name, option)</function>
		</title>
		<para>
		Checks and returns true if the given option/token is listed in the
		body of the given header. The header must have its body formated as a
		CSV list of tokens/option (like the Supported, Require,
		Content-Dispsition headers)
		body format
		</para>
		<para>Meaning of the parameters is as follows:</para>
		<itemizedlist>
		<listitem>
		<para><emphasis>hdr_name (string)</emphasis> - the name of the header to be
		checked. Note that all instances of that header will be checked (if the
		header has multiple instances in the SIP message). Any kind of header
		name is supported - RFC3261 standard, RFC extensions or custom names.
		</para>
		</listitem>
		<listitem>
		<para><emphasis>opt (string)</emphasis> - the option/tolen to be searched for.
		</para>
		</listitem>
		</itemizedlist>
		<para>
		<para>
		The function returns true if the options was found listed in one of the
		header instances. If no header was found, if the option was not found
		or if there was a parsing or runtime error, false will be returned.
		</para>
		This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE,
		FAILURE_ROUTE, BRANCH_ROUTE and LOCAL_ROUTE.
		</para>
		<example>
		<title><function>list_hdr_has_option</function> usage</title>
		<programlisting format="linespecific">
...
# check if 100rel is advertised
if (list_hdr_has_option("Supported", "100rel"))
	xlog("100rel option found\n");
...
</programlisting>
		</example>
	</section>

	<section id="func_list_hdr_add_option" xreflabel="list_hdr_add_option()">
		<title>
		<function moreinfo="none">list_hdr_add_option(hdr_name, option)</function>
		</title>
		<para>
		Add a new option/token at the end of the list in the body of the given
		header. The header must have its body formated as a
		CSV list of tokens/option (like the Supported, Require,
		Content-Disposition headers) body format
		</para>
		<para>
		Multiple add / remove operations can be performed over the same header.
		</para>
		<para>Meaning of the parameters is as follows:</para>
		<itemizedlist>
		<listitem>
		<para><emphasis>hdr_name (string)</emphasis> - the name of the header where the
		option has to be added. If multiple instances of that header are
		present in the SIP message, the add will be performed on the first
		instance. Any kind of header name is supported - RFC3261 standard,
		RFC extensions or custom names.
		</para>
		</listitem>
		<listitem>
		<para><emphasis>opt (string)</emphasis> - the option/token to be added to the
		CSV list. Note there is not verification for duplicated (if the newly
		added option is not already present in the header).
		</para>
		</listitem>
		</itemizedlist>
		<para>
		<para>
		The function returns true if the options was successfully added to
		the listed of the given header. If no header was found or if there was
		a parsing or runtime error, false will be returned.
		</para>
		This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE,
		FAILURE_ROUTE, BRANCH_ROUTE and LOCAL_ROUTE.
		</para>
		<example>
		<title><function>list_hdr_add_option</function> usage</title>
		<programlisting format="linespecific">
...
# add 100rel for advertising
if (!list_hdr_has_option("Supported", "100rel"))
    list_hdr_add_option("Supported", "100rel");
</programlisting>
		</example>
	</section>

	<section id="func_list_hdr_remove_option" xreflabel="list_hdr_remove_option()">
		<title>
		<function moreinfo="none">list_hdr_remove_option(hdr_name, option)</function>
		</title>
		<para>
		Removes an option/token from the list inside the body of the given
		header. The header must have its body formated as a
		CSV list of tokens/option (like the Supported, Require,
		Content-Dispsition headers)
		body format
		</para>
		<para>
		Multiple add / remove operations can be performed over the same header.
		</para>
		<para>Meaning of the parameters is as follows:</para>
		<itemizedlist>
		<listitem>
		<para><emphasis>hdr_name (string)</emphasis> - the name of the header where the
		option has to be removed from. If the option is duplicated in the same
		header, only the last one will be removed. If multiple instances of
		that header are present in the SIP message, the remove will be
		performed on all instance instance. Any kind of header name is
		supported - RFC3261 standard, RFC extensions or custom names.
		</para>
		</listitem>
		<listitem>
		<para><emphasis>opt (string)</emphasis> - the option/token to be removed from
		the CSV list. Note that if this the only option in the header, the
		whole header will be removed.
		</para>
		</listitem>
		</itemizedlist>
		<para>
		<para>
		The function returns true if the options was successfully removed from
		at least one heaer instance. If no header was found or if the
		token was not found or if there was a parsing or runtime error, false
		will be returned.
		</para>
		This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE,
		FAILURE_ROUTE, BRANCH_ROUTE and LOCAL_ROUTE.
		</para>
		<example>
		<title><function>list_hdr_remove_option</function> usage</title>
		<programlisting format="linespecific">
...
# add 100rel for advertising
if (list_hdr_has_option("Supported", "100rel"))
    list_hdr_remove_option("Supported", "100rel");
list_hdr_add_option("Supported", "optionX");
</programlisting>
		</example>
	</section>


	</section>
	<section>
		<title>Known Limitations</title>
		<para>
			Search functions are applied to the current message so
			modifications made to the sdp will be visible
			to the codec_exists functions( e.g. after
			calling codec_delete("speex") , codec_exists("speex")
			will return false ).
		</para>
	</section>
</chapter>