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

<chapter>
	
	<title>&adminguide;</title>
	
	<section id="overview" xreflabel="Overview">
	<title>Overview</title>
	<para>

The emergency module provides emergency call treatment for OpenSIPS, following the architecture i2 specification of the American entity NENA. (National Emergency Number Association). The NENA solution routes the emergency call to a closer gateway (ESGW) and this forward the call to a PSAP(call center responsible for answering emergency calls) that serves the area of ​​the caller, so this must consider the handling and transport of caller location information in the SIP protocol.

To attend this new need the NENA solution consists of several servers: to determine the location (LIS), to determine the area of emergency treatment depending on location (VPC), validate location stored (VDB), among others. Along with these elements have the SIP Proxy that interface with these servers to route the call. The OpenSIPS can do the functions of these SIP Proxy through this emergency module, may perform the function of a Call Server, Redirect Server and Routing Proxy, depending on the proposed scenario:
	</para>
	<itemizedlist>
		<listitem><para>
scenario I:  The VSP(Voip Serve Provide) retains control over the processing of emergency calls. The VSP’s Call Server implements the v2 interface that queries the VPC for routing information, with this information selects the proper ESGW, if normal routing fails routes calls via the PSTN using the contingency number(LRO).
		</para></listitem>
		<listitem><para>
scenario II: The VSP transfers all emergency calls to Routing Proxy provider using the v6 SIP interface. Once done transfer the VSP no longer participates in the call. The Routing Proxy provider implements the v2 interface, queries the VPC for for routing information, and forwards the call. 
		</para></listitem>
		<listitem><para>
scenario III: The VSP requests routing information for the Redirect Server operator, but remains part of the call. The Redirect Server obtains the routing information from the VPC. It returns the call to the VSP’s Call Server with routing information in the SIP Contact Header. The Call Server selects the proper ESGW based on this information.
		</para></listitem>
	</itemizedlist>
	<para>
The emergency module allows the OpenSIPS play the role of a Call Server, a Proxy or Redirect Server Routing within the scenarios presented depending on how it is configured.
	</para>
	<para>
		1.2. Scenario I: The VSP that originating the call is the same as handle the call and sends the routing information request to the VPC. 
	
		The emergency module through emergency_call() command  will check if the INVITE received is an emergency call. In this case, the OpenSIPS will get caller location information from specific headers and body in the INVITE. With this information along configuration parameters defined for this module, the opensips implements the v2 interface that queries the VPC for routing information (i.e., ESQK, LRO, and either the ERT or ESGWRI), selects the proper ESGW based on the ESGWRI. When the call ends the OpenSIPS receives BYE request, it warns the VPC for clean your data that is based on the call.	
		The &osips; through failure() command  will try to route the calls via the PSTN using a national contingency number(LRO) if normal routing fails.

	</para>
	<para>
		1.3.Scenario II: The VSP transfers the call to a Routing Server provider

		The emergency module through emergency_call() command  will check if the INVITE received is an emergency call. In this case, it will forward the call to a Routing Proxy that will interface with the VPC and route the call.		
		The OpenSIPS will leave the call, and all the request of this dialog received by the opensips will be forwarded to the Routing Server.

	</para>
	<para>
		1.4.Scenario III: The VSP requests routing information for the Redirect Server

		The emergency module through emergency_call() command  will check if the INVITE received is an emergency call. In this case, it requests routing information to Redirect Server. The Redirect has interface with the VPC and return to VSP's Call Server response whith routing informations on Contact header.		
		The Call Server uses this information to treat the call. When the emergency call ends, it must notify the Redirect Server that inform to VPC to release the resources.
	</para>
		To use this module should informs the mandatory parameters in script and make the correct filling out of the emergency module tables, in accordance with the role chosen within the described scenarios. For more details check the "Emergency calls using OpenSIPS".


	</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> Dialog - Dialoge module.</emphasis>.
			</para>
			</listitem>
			<listitem>
			<para>
				<emphasis> TM - Transaction module.</emphasis>.
			</para>
			</listitem>			
			<listitem>
			<para>
				<emphasis> RR - Record-Route module.</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>libcurl</emphasis>.
			</para>
			</listitem>
			</itemizedlist>
		</para>
	</section>
	</section>

	<section id="exported_parameters" xreflabel="Exported Parameters">
		<title>Exported Parameters</title>

	<section id="param_db_url" xreflabel="db_url">
		<title><varname>db_url</varname> (string)</title>
		<para>
		The database url must be specified.
		</para>
		<para>
		<emphasis>
			Default value is <quote>NULL</quote>.
		</emphasis>
		</para>
		<example>
		<title>Setting the <varname>db_url</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("emergency", "db_url", "mysql://opensips:opensipsrw@localhost/opensips”)
...
		</programlisting>
		</example>
	</section>

	<section id="param_db_table_routing" xreflabel="db_table_routing">
		<title><varname>db_table_routing</varname> (string)</title>
		<para>
		The name of the db table storing routing information to emergency calls.
		</para>
		<para>
		<emphasis>
			Default value is <quote>emergency_routing</quote>.
		</emphasis>
		</para>
		<example>
		<title>Setting the <varname>db_table_routing</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("emergency", "db_table_routing", "emergency_routing")
...
		</programlisting>
		</example>
	</section>

	<section id="param_db_table_report" xreflabel="db_table_report">
		<title><varname>db_table_report</varname> (string)</title>
		<para>
		The name of the db table that stores the emergency call report.
		</para>
		<para>
		<emphasis>
			Default value is <quote>emergency_report</quote>.
		</emphasis>
		</para>
		<example>
		<title>Setting the <varname>db_table_report</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("emergency", "db_table_report", "emergency_report")
...
		</programlisting>
		</example>
	</section>

	<section id="param_db_table_provider" xreflabel="db_table_provider">
		<title><varname>db_table_provider</varname> (string)</title>
		<para>
		The name of the db table that stores the nodes information of organization involved in emergency calls.

		</para>
		<para>
		<emphasis>
			Default value is <quote>emergency_service_provider</quote>.
		</emphasis>
		</para>
		<example>
		<title>Setting the <varname>db_table_provider</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("emergency", "db_table_provider", "emergency_service_provider")
...
		</programlisting>
		</example>
	</section>

	<section id="param_proxy_role" xreflabel="proxy_role">
		<title><varname>proxy_role</varname> (integer)</title>
		<para>
		This parameter define what role the opensips will take to treat emergency   
   		call:
			<para>
		    0 – The opensips is the Call Server in scenario I. In this role the 
		        opensips implements the V2 interface, directly queries the VPC for 
		        ESGWRI/ESQK, selects the proper ESGW given the ESGWRI and routes calls 
		        Via the PSTN using the LRO if routing fails.
			</para>
			<para>
		    1 – The opensips is the Call Server in scenario II that sends the INVITE on 
		        emergency call to a Routing Proxy provider. The Routing Proxy provider 
		        implements the V2 interface.
			</para>
			<para>
		    2 - The opensips is the Routing Proxy in scenario II. In this role the 
		        opensips implements the V2 interface, directly queries the VPC for 
		        ESGWRI/ESQK, selects the proper ESGW given the ESGWRI and routes calls 
		        Via the PSTN using the LRO if routing fails.
			</para>
			<para>
		    3 - The opensips is the Redirect Proxy in scenario III that receives the 
		        INVITE on emergency call from Call Server. The Redirect Server obtains 
		        the ESGWRI/ESQK from the VPC and sends in the SIP 3xx response to the 
		        Call Server.
			</para>	        
			<para>
		    4 - The opensips is the Call Server in scenario III that sends the INVITE on 
		 		emergency call to a Redirect Server. The Redirect Server obtains the 
		 		ESGWRI/ESQK from the VPC. It returns the call to the opensips with the 
		 		ESGWRI/ESQK in the header contact in the SIP response. The opensips  
		 		selects the proper ESGW based on the ESGWRI.
			</para>
		</para>
		<para>
		<emphasis>
			Default value is <quote>0</quote>.
		</emphasis>
		</para>
		<example>
		<title>Setting the <varname>proxy_role</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("emergency", "proxy_role", 0))
...
		</programlisting>
		</example>
	</section>

	<section id="param_url_vpc" xreflabel="url_vpc">
		<title><varname>url_vpc</varname> (string)</title>
		<para>
   		The VPC url that opensips request the routing information to emergency 
   		call. This VPC url has IP:Port format
		</para>
		<para>
		<emphasis>
			Default value is <quote>empty string</quote>.
		</emphasis>
		</para>
		<example>
		<title>Setting the <varname>url_vpc</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("emergency", "url_vpc", “192.168.0.103:5060”)
...
		</programlisting>
		</example>
	</section>

	<section id="param_emergency_codes" xreflabel="emergency_codes">
		<title><varname>emergency_codes</varname> (string)</title>
		<para>
   		Local emergency number. Opensips uses this number to recognize a emergency 
   		call beyond the username default defined by RFC-5031 (urn:service.sos.).
   		Along with the number should be given a brief description about this code.        
   		The format is code_number-description. It can register multiple emergency 
   		numbers.
		</para>
		<para>
		<emphasis>
			Default value is <quote>NULLg</quote>.
		</emphasis>
		</para>
		<example>
		<title>Setting the <varname>emergency_codes</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("emergency", "emergency_codes", “911-us emegency code”)
...
		</programlisting>
		</example>
	</section>

	<section id="param_timer_interval" xreflabel="timer_interval">
		<title><varname>timer_interval</varname> (interger)</title>
		<para>
   		Sets the time interval polling to make the copy in memory of the 
   		db_table_routing.
		</para>
		<para>
		<emphasis>
			Default value is <quote>10</quote>.
		</emphasis>
		</para>
		<example>
		<title>Setting the <varname>timer_interval</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("emergency","timer_interval",20)
...
		</programlisting>
		</example>
	</section>

	<section id="param_contingency_hostname" xreflabel="contingency_hostname">
		<title><varname>contingency_hostname</varname> (string)</title>
		<para>
   		The contingency_hostname is the url of the server que will route the call 
   		to the PSTN using the number of contingency.
		</para>
		<para>
		<emphasis>
			Default value is <quote>NULL</quote>.
		</emphasis>
		</para>
		<example>
		<title>Setting the <varname>contingency_hostname</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("emergency","contingency_hostname",“176.34,29.102:5060”)
...
		</programlisting>
		</example>
	</section>


	<section id="param_emergency_call_server" xreflabel="emergency_call_server">
		<title><varname>emergency_call_server</varname> (string)</title>
		<para>
		The emergency_call_server is the url of the Routing Proxy/Redirect Server
		that will handle  the emergency call in cenario II. Its is mandatory if Opensips 
		act as Call Server in scenario II (proxy_role = 1 and flag_third_enterprise = 0) 
		or Call Server in scenario III (proxy_role = 2).
		</para>
		<para>
		<emphasis>
			Default value is <quote>NULL</quote>.
		</emphasis>
		</para>
		<example>
		<title>Setting the <varname>emergency_call_server</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("emergency","emergency_call_server",“124.78.29.123:5060”)
...
		</programlisting>
		</example>
	</section>
	</section>


	<section id="exported_functions" xreflabel="exported_functions">
	<title>Exported Functions</title>
	<section id="func_emergency_call" xreflabel="emergency_call()">
		<title>
		<function moreinfo="none">emergency_call()</function>
		</title>
		<para>
   		Checks whether the incoming call is an emergency call, case it is treats, and  
   		routes the call to the destination determined by VPC.

   		The function returns true if is a emergency call and the treat was Ok.
		</para>
		<para>
		This function can be used from the <emphasis>REQUEST</emphasis> routes.
		</para>
		<example>
		<title><function moreinfo="none">emergency_call()</function> usage</title>
		<programlisting format="linespecific">
...
# Example of treat of emergency call

    if (emergency_call()){

        xlog("emergency call\n");
        t_on_failure("emergency_call");
        t_relay();
        exit;

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

	<section id="func_failure" xreflabel="failure()">
		<title>
		<function moreinfo="none">failure()</function>
		</title>
		<para>
   		This function is used when trying to route the emergency call to the 
   		destination specified by the VPC and doesn't work, then uses this function to 
   		make one last attempt for a contingency number.

   		The function returns true if the contingency treat was OK.
		</para>
		<para>
		This function can be used from the <emphasis>FAILURE</emphasis> routes.
		</para>
		<example>
		<title><function moreinfo="none">failure()</function> usage</title>
		<programlisting format="linespecific">
...
# Example od treat of contingency in emergency call

    if (failure()) {
        if (!t_relay()) {
           send_reply(500,"Internal Error");
        };
        exit;
    }
...
		</programlisting>
		</example>
	</section>

	</section>

</chapter>

