<?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;

]>

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

<chapter>
    
    <title>&adminguide;</title>

    <section>
	<title>Overview</title>
	<para>Module for updating ISUP encapuslated in SIP (SIP-T/SIP-I)</para>
	<para>
	The sipt module can be used to update various ss7 headers contained inside
	a message. 
	</para>
	</section>
	<section>
	<title>Dependencies</title>
	<para>
	    The module depends on the following modules (in the other words the
		listed modules must be loaded before this module):
	    <itemizedlist>
		<listitem>
		    <para><emphasis>none</emphasis></para>
		</listitem>
	    </itemizedlist>
	</para>
    </section>

    <section>
	<title>Functions</title>
	<section id="sipt.f.sipt_destination">
		<title><function moreinfo="none">sipt_destination(destination, hops, nai)</function></title>
		<para>
			updates the IAM in the body if it exists, setting the called party number to <quote>destination</quote>
			with the nature address specified in <quote>nai</quote> and decrementing the hop counter value if present.
			If the hop counter header is missing it will be added with the value of <quote>hops</quote>.
		</para>
		<example>
			<title><function moreinfo="none">sipt_destination(destination, hops, nai)</function> usage</title>
			<programlisting format="linespecific">
...
# update the destination number to our current request uri, 
# setting nature of address to international
$rU = "19495551234";
sipt_destination($rU, 31, 4);
...
</programlisting>
		</example>
	</section>
	<section id="sipt.f.sipt_set_bci_1">
		<title><function moreinfo="none">sipt_set_bci_1(charge_indicator, called_status, called_category, e2e_indicator)</function></title>
		<para>
			updates the first byte of the backward call indicator in the ACM or COT in the body if setting the 
			Charge Indicator to <quote>charge_indicator</quote>, the Called party's status indicator in <quote>called_status</quote>, 
			the Called party's category indicator in <quote>called_category</quote> and the End to End Method Indicator
			with the value of the value of <quote>e2e_indicator</quote>.
		</para>
		<example>
			<title><function moreinfo="none">sipt_destination(destination, hops, nai)</function> usage</title>
			<programlisting format="linespecific">
...
# set bci for charging, subscriber free, ordinary, no e2e available
sipt_set_bci_1("2", "1", "1", "0");
...
</programlisting>
		</example>
	</section>
	<section id="sipt.f.sipt_set_calling">
		<title><function moreinfo="none">sipt_set_calling(origin, nai, presentation, screening)</function></title>
		<para>
			updates the IAM in the body if it exists, setting (or adding) the calling party number to <quote>origin</quote>
			with the nature address specified in <quote>nai</quote> and setting the presentation and screening values to 
			 <quote>presentation</quote> and <quote>screening</quote>.
		</para>
		<example>
			<title><function moreinfo="none">sipt_set_calling(origin, nai, presentation, screening)</function> usage</title>
			<programlisting format="linespecific">
...
# update the calling party to the value in the from header
sipt_set_calling($fU, 4, 0, 3);
...
</programlisting>
		</example>
	</section>
</section>
<section>
        <title>Exported pseudo-variables</title>
	<section id="sipt.v.sipt_presentation">
		<title><varname>$sipt(calling_party_number.presentation) / $sipt_presentation</varname></title>
		<para>
			Returns the value of the Address presentation restricted indicator contained in the
			Calling Party Number header of the IAM message if it exists.
			Returns -1 if there isn't a Calling Party Number header.
		</para>
		<table>
			<title>Address Presentation Restricted Indicator Values</title>
			<tgroup cols="2">
				<tbody>
					<row><entry>0</entry><entry>presentation allowed</entry></row>
					<row><entry>1</entry><entry>presentation restricted</entry></row>
					<row><entry>2</entry><entry>address not avail (national use)</entry></row>
					<row><entry>3</entry><entry>spare</entry></row>
				</tbody>
			</tgroup>
		</table>
		<example>
			<title><function moreinfo="none">sipt_presentation pseudo-variable</function> usage</title>
			<programlisting format="linespecific">
...
# add privacy header if restriction is requested 
if($sipt(calling_party_number.presentation) == 1)
{
	append_hf("Privacy: id\r\n");
	$fn = "Anonymous";
}

...
</programlisting>
		</example>
	</section>
	<section id="sipt.v.sipt_screening">
		<title><varname>$sipt(calling_party_number.screening) / $sipt_screening</varname></title>
		<para>
			Returns the value of the Screening Indicator contained in the
			Calling Party Number header of the IAM message if it exists.
			Returns -1 if there isn't a Calling Party Number header.
		</para>
		<table>
			<title>Screening Indicator Values</title>
			<tgroup cols="2">
				<tbody>
					<row><entry>0</entry><entry>Reserved (user provided, not verified)</entry></row>
					<row><entry>1</entry><entry>User Provided, Verified and Passed</entry></row>
					<row><entry>2</entry><entry>Reserved (user provided, verified and failed)</entry></row>
					<row><entry>3</entry><entry>Network provided</entry></row>
				</tbody>
			</tgroup>
		</table>
		<example>
			<title><function moreinfo="none">sipt_screening pseudo-variable</function> usage</title>
			<programlisting format="linespecific">
...

# remove P-Asserted-Identity header if the screening isn't verified 
# or network provided
$avp(s:screening) = $sipt(calling_party_number.screening);
if($avp(s:screening) != 1 &amp;&amp; $avp(s:screening) != 3)
{
	remove_hf("P-Asserted-Id");
}

...
</programlisting>
		</example>
	</section>
	<section id="sipt.v.sipt_hop_counter">
		<title><varname>$sipt(hop_counter) / $sipt_hop_counter</varname></title>
		<para>
			Returns the value of the Hop Counter for the IAM message if it exists.
			Returns -1 if there isn't a hop counter.
		</para>
		<example>
			<title><function moreinfo="none">sipt_hop_counter pseudo-variable</function> usage</title>
			<programlisting format="linespecific">
...
# get the hop counter and update the Max-Forwards header if it exists
$avp(s:hop) = $sipt(hop_counter);
if($avp(s:hop) > 0)
{
	remove_hf("Max-Forwards");
	append_hf("Max-Forwards: $avp(s:hop)\r\n");
}

...
</programlisting>
		</example>
	</section>
	<section id="sipt.v.sipt_cpc">
		<title><varname>$sipt(calling_party_category) / $sipt(cpc) / $sipt_cpc</varname></title>
		<para>
			Returns the value of the Calling Party Category for the IAM message.
			Returns -1 if there is a parsing error.
		</para>
		<example>
			<title><function moreinfo="none">sipt_cpc pseudo-variable</function> usage</title>
			<programlisting format="linespecific">
...
# get the Cpc code and set put it in a custom sip header
append_hf("X-CPC: $sipt(cpc)\r\n");

...
</programlisting>
		</example>
	</section>
	<section id="sipt.v.sipt_calling_party_nai">
		<title><varname>$sipt(calling_party_number.nature_of_address) / $sipt.(calling_party_number.nai) / $sipt_calling_party_nai</varname></title>
		<para>
			Returns the value of the Nature of Address Indicator
			of the Calling Party for the IAM message.
			Returns -1 if there is a parsing error or if
			the Calling Party Number is not present.
		</para>
		<table>
			<title>Calling Nature of Address Values</title>
			<tgroup cols="2">
				<tbody>
					<row><entry>0</entry><entry>Spare</entry></row>
					<row><entry>1</entry><entry>Subscriber Number (national use)</entry></row>
					<row><entry>2</entry><entry>Unknown (national use)</entry></row>
					<row><entry>3</entry><entry>National (significant) number (national use)</entry></row>
					<row><entry>4</entry><entry>International use</entry></row>
				</tbody>
			</tgroup>
		</table>
		<example>
			<title><function moreinfo="none">sipt_calling_party_nai pseudo-variable</function> usage</title>
			<programlisting format="linespecific">
...
# get the Calling Nai and add country code if national
if($sipt(calling_party_number.nai) == 3)
{
	$fU = "32" + "$fU";
}

...
</programlisting>
		</example>
	</section>
	<section id="sipt.v.sipt_called_party_nai">
		<title><varname>$sipt(called_party_number.nature_of_address) / $sipt(called_party_number.nai) / $sipt_called_party_nai</varname></title>
		<para>
			Returns the value of the Nature of Address Indicator
			of the Called Party for the IAM message.
			Returns -1 if there is a parsing error.
		</para>
		<table>
			<title>Called Nature of Address Values</title>
			<tgroup cols="2">
				<tbody>
					<row><entry>0</entry><entry>Spare</entry></row>
					<row><entry>1</entry><entry>Subscriber Number (national use)</entry></row>
					<row><entry>2</entry><entry>Unknown (national use)</entry></row>
					<row><entry>3</entry><entry>National (significant) number</entry></row>
					<row><entry>4</entry><entry>International use</entry></row>
					<row><entry>5</entry><entry>Network-specific number (national use)</entry></row>
				</tbody>
			</tgroup>
		</table>
		<example>
			<title><function moreinfo="none">sipt_called_party_nai pseudo-variable</function> usage</title>
			<programlisting format="linespecific">
...
# get the Called Nai and add country code if national
if($sipt(called_party_number.nai) == 3)
{
	$rU = "32" + "$rU";
}

...
</programlisting>
		</example>
	</section>
	<section id="sipt.v.sipt_event_info">
		<title><varname>$sipt(event_info)</varname></title>
		<para>
			Returns the value of the Event Info header
			of the CPG message.
			Returns -1 if there is a parsing error.
		</para>
		<table>
			<title>Event Info Values</title>
			<tgroup cols="2">
				<tbody>
					<row><entry>0</entry><entry>Spare</entry></row>
					<row><entry>1</entry><entry>ALERTING</entry></row>
					<row><entry>2</entry><entry>PROGRESS</entry></row>
					<row><entry>3</entry><entry>In-band information or an appropriate pattern is now available</entry></row>
					<row><entry>4</entry><entry>Call forward on busy</entry></row>
					<row><entry>5</entry><entry>Call forward on no reply</entry></row>
					<row><entry>6</entry><entry>Call forward unconditional</entry></row>
				</tbody>
			</tgroup>
		</table>
	</section>
	<section id="sipt.v.sipt_backward_call_indicator_charge_indicator">
		<title><varname>$sipt(backward_call_indicator.charge_indicator)</varname></title>
		<para>
			Returns the value of the charge indication 
			of the backward call indicator header in 
			the ACM or COT message.
			Returns -1 if there is a parsing error.
		</para>
		<table>
			<title>Charge Indicator Values</title>
			<tgroup cols="2">
				<tbody>
					<row><entry>0</entry><entry>no indication</entry></row>
					<row><entry>1</entry><entry>no charge</entry></row>
					<row><entry>2</entry><entry>charge</entry></row>
					<row><entry>3</entry><entry>spare</entry></row>
				</tbody>
			</tgroup>
		</table>
	</section>

</section>
</chapter>

