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

<chapter>
	

	<title>&adminguide;</title>
	
	<section id="overview" xreflabel="Overview">
		<title>Overview</title>
		<para>
		This module provides OpenSIPS support for shared call appearances (SCA)
		as defined by BroadWorks SIP Access Side Extensions Interface specifications.
		The SCA mechanism is a fundamental building block for a variety of enhanced 
		telephony services. Features like attendant console, line extensions,
		and key system emulation cannot be delivered without some mechanism for
		sharing call appearances across access devices. Although SIP (RFC 3261)
		by itself offers no inherent semantics for supporting SCA features, when
		coupled with an appropriate instantiation of the “SIP Specific Event Notification”
		framework (RFC 3265), these services can be deployed quite easily in a 
		distributed network.
		</para>
		<para>
		A shared line is an address of record managed by central
		controlling element, such as an application server. The application server 
		allows multiple endpoints to register locations against the address of record.
		The application server is responsible for policing who can register and who 
		cannot register against the shared line.
		</para>
		<para>
		The module enables the handling of "call-info" and "line-seize"
		events inside the presence module. It is used with the general event
		handling module: presence and it constructs and adds "Call-Info" headers
		to notification events.
		</para>
	</section>

	<section>
		<title>Usage modes</title>
		<para>
		The module can be used in two ways (depending on who is doing the
		publishing of the "call-info" data:
		</para>
		<itemizedlist>
			<listitem><para>external publishing - the "call-info" data
			is received from a third party via SIP PUBLISH requests. In this
			mode, the modules simply distributes the SCA info, it is not 
			producing any of it - a third-party application must publish 
			"call-info" events to the presence server.
			</para></listitem>
			<listitem><para>internal publishing - the "call-info" data
			is internally generated by the module, based on the information
			received from the dialog module - what calls are using what 
			line/index, what is the state of the call, etc. There is no SIP
			PUBLISH in this case and there is no need for a third-party - 
			the module is self-sufficient and stand alone as functionality.
			</para></listitem>
		</itemizedlist>
		<para>The used mode can be controlled via the module parameter 
		"disable_dialog_support_for_sca" - see below in the parameter's
		section.
		</para>

		<section>
			<title>External publishing</title>
			<para>
			The module does not currently implement any authorization
			rules.  It assumes that publish requests are only issued by
			a third-party application and subscribe requests only by
			subscriber to call-info and line-seize events.  Authorization
			can thus be easily done by &osips; configuration file before
			calling handle_publish() and handle_subscribe() functions.
			</para>
			<para>
			To get better understanding on how the module works please take a
			look at the follwing figure:
			<programlisting format="linespecific">
<![CDATA[
   caller       proxy &   callee        watcher        publisher
alice@example  presence  bob@example  watcher@example
                 server                       
     |             |           |           |              |
     |             |<-----SUBSCRIBE bob----|              |
     |             |------200 OK---------->|              |
     |             |------NOTIFY---------->|              |
     |             |<-----200 OK-----------|              |
     |             |           |           |              |
     |--INV bob--->|           |           |              |
     |             |--INV bob->|           |              |
     |             |<-100------|           |              |
     |             |<-----PUBLISH(alerting)---------------|
     |             |------200 OK------------------------->|
     |             |------NOTIFY---------->|              |
     |             |<-----200 OK-----------|              |
     |             |           |           |              |
     |             |<-180 ring-|           |              |
     |<--180 ring--|           |           |              |
     |             |           |           |              |
     |             |           |           |              |
     |             |<-200 OK---|           |              |
     |<--200 OK----|           |           |              |
     |             |<-----PUBLISH(active)-----------------|
     |             |------200 OK------------------------->|
     |             |------NOTIFY---------->|              |
     |             |<-----200 OK-----------|              |
     |             |           |           |              |
]]>
			</programlisting>
			<itemizedlist>
				<listitem><para>
				The watcher subscribes the "Event: dialog" of Bob.
				</para></listitem>
				<listitem><para>
				Alice calls Bob.
				</para></listitem>
				<listitem><para>
				The publisher is publishing the "alerting" state for Bob.
				</para></listitem>
				<listitem><para>
				PUBLISH is received and handled by presence module.
				Presence module updates the "presentity".
				Presence module checks for active watchers of the presentity.
				The active watcher is notified via a NOTIFY SIP request.
				</para></listitem>
				<listitem><para>
				Bob answers the call.
				</para></listitem>
				<listitem><para>
				The publisher is publishing the "active" state for Bob.
				</para></listitem>
				<listitem><para>
				PUBLISH is received and handled by presence module.
				Presence module updates the "presentity".
				Presence module checks for active watchers of the presentity.
				The active watcher is notified via a NOTIFY SIP request.
				</para></listitem>
			</itemizedlist>
			</para>
		</section>

		<section>
			<title>Internal publishing</title>
			<para>
			In this mode, the module requires the "dialog" module to be
			loaded into OpenSIPS. All the publishing will be automatically
			done (the modules will exchange data directly via C API).
			</para>
			<para>
			From presence perspective, the OpenSIPS script must be configured
			to handle the SUBSCRIBE requests only (there is no need for PUBLISH
			handling as there is no SIP publishing in this mode). So be sure
			to use the "handle_subscribe()" function (from presence module) in
			the script.
			</para>
			<para>
			To trigger the internal publishing (from the dialog module) for a
			certain call, use the "sca_set_calling_line()" or
			"sca_set_called_line()" functions from the script when handling a
			new call. These functions will do all the work (creating dialog, 
			setting the internal publishing, etc) - you just need to use them
			and eventually specify the name of the line (if other then the one
			from the SIP INVITE) - see the below documentation.
			</para>
			<para>
			LIMITATIONS : in this mode, the module does not really check if the
			line exists or not (like defined) - it blindly trust the traffic;
			also there is no check on how many indexes are for each line. Such
			information (lines and indexes) are not provisioned into the module,
			but the module will dynamically accept and handle any line and index
			based on the SIP traffic.
			</para>
		</section>
	</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>presence</emphasis>.
				</para>
				</listitem>
				<listitem>
				<para>
				<emphasis>dialog</emphasis>.
				</para>
				</listitem>
			</itemizedlist>
			</para>
		</section>

		<section>
			<title>External Libraries or Applications</title>
			<para>
			None.
			</para>
		</section>
	</section>

	<section id="exported_parameters" xreflabel="Exported Parameters">
		<title>Exported Parameters</title>
		<section id="param_call_info_timeout_notification" xreflabel="call_info_timeout_notification">
			<title><varname>call_info_timeout_notification</varname> (int)</title>
			<para>
			Enables or disables call_info event timeout notifications.
			</para>
			<para><emphasis>Default value is <quote>1</quote></emphasis> (enabled).</para>
			<example>
			<title>Set <varname>call_info_timeout_notification</varname> parameter</title>
			<programlisting format="linespecific">
...
modparam("presence_callinfo", "call_info_timeout_notification", 0)
...
			</programlisting>
			</example>
		</section>

		<section id="param_line_seize_timeout_notification" xreflabel="line_seize_timeout_notification">
			<title><varname>line_seize_timeout_notification</varname> (int)</title>
			<para>
			Enables or disables line_seize event timeout notifications.
			</para>
			<para><emphasis>Default value is <quote>0</quote></emphasis> (disabled).</para>
			<example>
			<title>Set <varname>line_seize_timeout_notification</varname> parameter</title>
			<programlisting format="linespecific">
...
modparam("presence_callinfo", "line_seize_timeout_notification", 1)
...
			</programlisting>
			</example>
		</section>

		<section id="param_disable_dialog_support_for_sca" xreflabel="disable_dialog_support_for_sca">
			<title><varname>disable_dialog_support_for_sca</varname> (int)</title>
			<para>
			Disables the internal publishing of the "call-info" events (generated by the dialog module).
			The publishing is expected to be done via SIP PUBLISH from a third-party. See
			the wroking mode described in the beginning of this document.
			</para>
			<para><emphasis>Default value is <quote>0</quote></emphasis> (not disabled).</para>
			<example>
			<title>Set <varname>disable_dialog_support_for_sca</varname> parameter</title>
			<programlisting format="linespecific">
...
modparam("presence_callinfo", "disable_dialog_support_for_sca", 1)
...
			</programlisting>
			</example>
		</section>

		<section id="param_line_hash_size" xreflabel="line_hash_size">
			<title><varname>line_hash_size</varname> (int)</title>
			<para>
			Allows you to controll the size of the internal hash table used for storing the
			information about the lines and indexes (in the internal publishing mode).
			</para>
			<para>
			The value must be a power of 2. You may consider increasing the value if using
			a large set of lines (>1000).
			</para>
			<para><emphasis>Default value is <quote>64</quote></emphasis>.</para>
			<example>
			<title>Set <varname>line_hash_size</varname> parameter</title>
			<programlisting format="linespecific">
...
modparam("presence_callinfo", "line_hash_size", 128)
...
			</programlisting>
			</example>
		</section>

	</section>

	<section id="exported_functions" xreflabel="exported_functions">
		<title>Exported Functions</title>

		<section id="func_sca_set_calling_line" xreflabel="sca_set_calling_line()">
			<title>
			<function moreinfo="none">sca_set_calling_line([line])</function>
			</title>
			<para>
			The function (to be used only in internal publishing mode) is setting
			for the current new call (initinal INVITE) the outbound line - the line
			used for calling out.
			</para>
			<para>
			If no parameter is provided, the name of the line is taken from the
			SIP FROM header of the INVITE. You can override that by providing 
			the name of the line as a string parameter - be careful as the value must be
			a SIP URI !
			</para>
			<para>
			This function can be used from REQUEST_ROUTE.
			</para>
			<example>
			<title><function>sca_set_calling_line()</function> usage</title>
			<programlisting format="linespecific">
...
	if (is_method("INVITE") and !has_totag()) {
		sca_set_calling_line();
	}
...
</programlisting>
			</example>
		</section>

		<section id="func_sca_set_called_line" xreflabel="sca_set_called_line()">
			<title>
			<function moreinfo="none">sca_set_called_line([line])</function>
			</title>
			<para>
			The function (to be used only in internal publishing mode) is setting
			for the current new call (initinal INVITE) the inbound line - the line
			the call was received on.
			</para>
			<para>
			If no parameter is provided, the name of the line is taken from the
			SIP RURI of the INVITE. You can override that by providing 
			the name of the line as a string parameter - be careful as the value must be
			a SIP URI ! Variables are accepted.
			</para>
			<para>
			This function can be used from REQUEST_ROUTE.
			</para>
			<example>
			<title><function>sca_set_called_line()</function> usage</title>
			<programlisting format="linespecific">
...
	if (is_method("INVITE") and !has_totag()) {
		sca_set_called_line();
	}
...
</programlisting>
			</example>
		</section>

	</section>

</chapter>

