<?xml version='1.0' encoding='UTF-8'?>
<!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;

]>

<section id="presence_b2b"><title>Presence B2B UA</title>

    <sectioninfo><authorgroup>
	<author>
		<firstname>Vaclav</firstname>
		<surname>Kubart</surname>
		<affiliation><orgname>Iptel/Tekelec</orgname></affiliation>
		<email>vaclav.kubart@iptel.org</email>
	</author>
	</authorgroup></sectioninfo>

<para>This module acts as back to back user agent for presence events. In the
future it will do subscriptions to reg events and presence with resource lists
too.</para>

<para>It is accessible only using the internal Query Status API (QSA). Everywhere
(in the C code) where you need subscriptions to presentity status, you only create
an internal subscription to it and the rest is done by this module. 
It processes the internal subscription and creates a SIP subscription 
(SUBSCRIBE-NOTIFY dialog) to requested presentity. Every NOTIFY request produces 
new QSA message with status information into destination message queue.
</para>

<para>Instead of this module can be used PA module with parameter
<varname>accept_internal_subscriptions</varname> set to 1. In that case the
subscription will be only to internal status hold by PA.
</para>

<para>For every requested (record, subscriber) a new SIP subscription is created.
This is due to authorization of such subscriptions - B2B UA can't decide about
authorization rules, thus it has to leave it on the presence server to which it
creates the subscription and this means, that it has to create the subscription
as a subscriber. There is a possibility to do subscriptions with the same
To + From only once, but this is left for future optimalizations (it will
probably not help a lot).
</para>

<section id="presence_b2b.dependencies"><title>Dependencies</title>
<itemizedlist><title>Modules</title>
	<listitem><para><application>tm</application></para></listitem>
	<listitem><para><application>dialog</application></para></listitem>
</itemizedlist>
<itemizedlist><title>Libraries</title>
		<listitem><para><application>libcds (internal)</application></para></listitem>
		<listitem><para><application>libpresence (internal)</application></para></listitem>
</itemizedlist>
</section>

<section><title>Usage</title>
<para>This module can be used by RLS module (e.g. RLS module does internal
subscriptions to "presence" which can be handled by this module or PA module).
</para>
<para>In near future it will be used by PA module for subscribing to users; this
could be useful with UACs capable to process SUBSCRIBE/NOTIFY but not using
PUBLISH for presence state publication (like Windows Messenger).
</para>
</section>

<include xmlns="http://www.w3.org/2001/XInclude" href="params.xml"/>
<include xmlns="http://www.w3.org/2001/XInclude" href="functions.xml"/>

<!--<section><title>Configuration example</title>
<para></para>-->
<example><title>Configuration example</title>
<programlisting><![CDATA[
...
loadmodule "/home/kubartv/SER/lib/ser/modules/tm.so"
loadmodule "/home/kubartv/SER/lib/ser/modules/dialog.so"
loadmodule "/home/kubartv/SER/lib/ser/modules/presence_b2b.so"

...
modparam("presence_b2b", "presence_route", "<sip:my-sip-server.domain.com;lr>")
modparam("presence_b2b", "on_error_retry_time", 600)
modparam("presence_b2b", "wait_for_term_notify", 33)
modparam("presence_b2b", "resubscribe_delta", 15)
modparam("presence_b2b", "min_resubscribe_time", 55)
modparam("presence_b2b", "default_expiration", 667)
...

route {

	...

	if (uri==myself) {
		
		...
		
 		if (method=="NOTIFY") {
 			if (!t_newtran()) {
 			   log(1, "newtran error\n");
 			   sl_reply_error();
 			};
 			if (!handle_notify()) {
 				t_reply("481", "Unable to handle notification");
 			}
 			break;
 		};
		
		...
	}

	...
	
}
]]>
</programlisting>
</example>
<!--</section> -->

</section>

