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

<chapter>
	
	<title>&adminguide;</title>
	
	<section id="overview" xreflabel="Overview">
	<title>Overview</title>
	<para>
		The <acronym>SIGNALING</acronym> module comes as a wrapper over 
		tm and sl modules and offers one function to be called by the modules
		that want to send a reply. 
	</para>
	<para>
		The logic behind the module is to first search if a transaction is
		created and if so, send a state full reply, using tm module, otherwise
		send a stateless reply with the function exported by sl.
		In this way, the script writer still has the call on how the transaction 
		should be handled, state full or stateless and the reply is send 
		accordingly to his choice.
	</para>
	<para>
		For example, if you do a t_newtran() in the script before doing save() 
		(for registration), the function will automatically send the reply in 
		stateful mode as a transaction is available. If no transaction is done, 
		the reply will be sent in stateless way (as now).
	</para>
	<para>
		By doing this, we have the possibility to have same module sending 
		either stateful either stateless replies, by just controlling this from 
		the script (if we create or not a transaction).
		So, the signalling will be more coherent as the replies will be sent 
		according to the transaction presence (or not).
	</para>
	<para>
	Moreover, this module offers the possibility of loading only one 
	of the module, sl or tm, and send reply using only the module that is 
	loaded. This is useful as not in all cases a user desires to send 
	stateful or stateless replies and he should not be forced to load the 
	module only because the send reply interface requires it.
	</para>
	</section>
	<section id="dependencies" xreflabel="Dependencies">
	<title>Dependencies</title>
	<section>
		<title>&osips; Modules</title>
		<para>
		At least one of the following modules must be loaded before this module:
			<itemizedlist>
			<listitem>
			<para>
				<emphasis>sl</emphasis>.
			</para>
			</listitem>
			<listitem>
			<para>
				<emphasis>tm</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_parameters" xreflabel="Exported Parameters">
	<title>Exported Parameters</title>
		<para>
		<itemizedlist>
			<listitem>
			<para>
				<emphasis>None</emphasis>.
			</para>
			</listitem>
		</itemizedlist>
		</para>
	</section>

	<section id="exported_functions" xreflabel="exported_functions">
	<title>Exported Functions</title>
	<section id="func_send_reply" xreflabel="send_reply()">
		<title>
		<function moreinfo="none">send_reply(code, reason)</function>
		</title>
		<para>
		For the current request, a reply is sent back having the given code 
		and text reason. The reply is sent stateless or statefull depending 
		on which module is loaded and if a transaction was created, as 
		explained above.
		</para>
		<para>Meaning of the parameters is as follows:</para>
		<itemizedlist>
		<listitem>
			<para><emphasis>code (int)</emphasis> - Return code.
			</para>
		</listitem>
		<listitem>
			<para><emphasis>reason (string)</emphasis> - Reason phrase.
			</para>
		</listitem>
		</itemizedlist>
		<para>
		This function can be used from REQUEST_ROUTE, ERROR_ROUTE.
		</para>
		<example>
		<title><function>sl_send_reply</function> usage</title>
		<programlisting format="linespecific">
...
send_reply(404, "Not found");
...
send_reply($err.rcode, $err.rreason);
...
		</programlisting>
		</example>
	</section>
	</section>

	<section id="exported_pseudo_variables" xreflabel="Exported Variables">
	<title>Exported Variables</title>
	<section id="pv_sig_local_totag" xreflabel="$sig_local_totag">
		<title>$sig_local_totag</title>
		<para>This variable returns the local To-tag that will be used
		by OpenSIPS for locally sending replies to the current SIP request.
		Yes, this variable should be used only in the context of a SIP
		request and it should be used only in conjunction with the 
		using <xref linkend="func_send_reply"/>.
		</para>
		<para>
		Whenever you use it, be sure that the function is used in the same
		stateful / stateless SIP mode as the following replying function.
		Otherwise you may get different values for the To-tag!!
		</para>
		<para>
		NOTE: the variable returns the To-Tag that will be used by OpenSIPS
		in the locally generated reply. This may be completly different from
		the To-tag in the replies received and forwarded by OpenSIPS.
		</para>
		<example>
		<title>Usage of <varname>$sig_local_totag</varname> variable</title>
<programlisting>
...
# stateful handling
t_newtran();
xlog("the To-tag to be used is $sig_local_totag \n");
send_reply();  # or t_reply();
...
# stateless handling
xlog("the To-tag to be used is $sig_local_totag \n");
send_reply(); # or sl_send_reply();
...
</programlisting>
		</example>
	</section>
	</section>

</chapter>

