sipt_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 "../../../../doc/docbook/entities.xml">
%docentities;

]>

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

<chapter>

    <title>&adminguide;</title>

    <section>
	<title>Overview</title>
	<para>Module for updating ISUP encapsulated 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 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[, terminator=1])</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>.  If
			<quote>terminator</quote> is set to 1, then F will be appended to digit string to indicate the number
			is complete (default).
		</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 id="sipt.f.sipt_forwarding">
		<title><function moreinfo="none">sipt_forwarding(origin, nai)</function></title>
		<para>
			updates the IAM in the body if it exists, setting (or adding) the forwarding number to <quote>origin</quote>
			with the nature address specified in <quote>nai</quote>.
		</para>
		<example>
			<title><function moreinfo="none">sipt_set_calling(origin, nai)</function> usage</title>
			<programlisting format="linespecific">
...
# update the forwarding number to the value in the from header
sipt_forwarding($avp(s:forwarding_number), 3);
...
</programlisting>
		</example>
	</section>
	<section id="sipt.f.sipt_has_isup_body">
		<title><function moreinfo="none">sipt_has_isup_body()</function></title>
		<para>
			The function returns <emphasis>true</emphasis> if the SIP message
			has an ISUP body attached.
		</para>
		<example>
			<title><function moreinfo="none">sipt_has_isup_body()</function> usage</title>
			<programlisting format="linespecific">
...
if(sipt_has_isup_body())
{
    # do interesting stuff here
}
...
</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_calling_party_number">
		<title><varname>$sipt(calling_party_number)</varname></title>
		<para>
			Returns the value (Address signal) 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>
	</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_called_party_number">
		<title><varname>$sipt(called_party_number)</varname></title>
		<para>
			Returns the value (Address signal) of the Called Party for the IAM message.
			Returns -1 if there is a parsing error or if
			the Called Party Number is not present.
		</para>
	</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 id="sipt.v.sipt_redirection_info">
		<title><varname>$sipt(redirection_info) / $sipt_redirection_info</varname></title>
		<para>
			Returns call diversion information header from ISUP
			Returns "Redirecting reason" or -1 if no call diversion information found.
		</para>
		<table>
			<title>Redirecting reason Values</title>
			<tgroup cols="2">
				<tbody>
					<row><entry>0</entry><entry>Unknown</entry></row>
					<row><entry>1</entry><entry>User busy</entry></row>
					<row><entry>2</entry><entry>PROGRESS</entry></row>
					<row><entry>3</entry><entry>no reply</entry></row>
					<row><entry>4</entry><entry>deflection during alerting</entry></row>
					<row><entry>5</entry><entry>deflection immediate response</entry></row>
					<row><entry>6</entry><entry>mobile subscriber not reachable</entry></row>
				</tbody>
			</tgroup>
		</table>
	</section>
        	<section id="sipt.v.sipt_redirection_number">
		<title><varname>$sipt(redirection_number) / $sipt_redirection_number</varname></title>
		<para>
			Returns number to which redirection will triggered
			Returns -1 if there is a parsing error.
		</para>
		<example>
			<title><function moreinfo="none">sipt_redirection_number</function> usage</title>
			<programlisting format="linespecific">
...
# get the redirection number
$avp(s:redir_num) = $sipt(redirection_number);

...
</programlisting>
		</example>
	</section>
	<section id="sipt.v.sipt_redirection_number_nai">
		<title><varname>$sipt(redirection_number.nai) / $sipt_redirection_number_nai</varname></title>
		<para>
			Returns NAI for redirection number from ISUP
			Returns NAI for redirection number or -1 if no info found.
		</para>
		<table>
			<title>Redirecting number NAI 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>
	</section>

	<section id="sipt.v.sipt_redirection_information_reason">
		<title><varname>$sipt(redirection_information.reason)</varname></title>
		<para>
			Returns redirection reason from Redirection information from ISUP or -1 if no Redirection information found.
		</para>
	</section>

	<section id="sipt.v.sipt_redirection_information_original_reason">
		<title><varname>$sipt(redirection_information.original_reason)</varname></title>
		<para>
			Returns original redirection reason from Redirection information from ISUP or -1 if no Redirection information found.
		</para>
	</section>

	<section id="sipt.v.sipt_redirecting_number_nai">
		<title><varname>$sipt(redirecting_number.nai)</varname></title>
		<para>
			Returns NAI for redirecting number from ISUP or -1 if no redirecting number found.
		</para>
	</section>

	<section id="sipt.v.sipt_redirecting_number">
		<title><varname>$sipt(redirecting_number)</varname></title>
		<para>
			Returns redirecting number from ISUP or -1 if no redirecting number found.
		</para>
	</section>

	<section id="sipt.v.sipt_original_called_number_nai">
		<title><varname>$sipt(original_called_number.nai)</varname></title>
		<para>
			Returns NAI for original called number from ISUP or -1 if no original called number found.
		</para>
	</section>

	<section id="sipt.v.sipt_original_called_number">
		<title><varname>$sipt(original_called_number)</varname></title>
		<para>
			Returns original called number from ISUP or -1 if no original called number found.
		</para>
	</section>

	<section id="sipt.v.sipt_generic_number_nai">
		<title><varname>$sipt(generic_number.nai)</varname></title>
		<para>
			Returns NAI for generic number from ISUP or -1 if no generic number found.
		</para>
	</section>

	<section id="sipt.v.sipt_generic_number">
		<title><varname>$sipt(generic_number)</varname></title>
		<para>
			Returns generic number from ISUP or -1 if no generic number found.
		</para>
	</section>

</section>
</chapter>