kamailio/modules_k/pua_mi/doc/pua_mi_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 "../../../docbook/entities.xml">
%docentities;

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

<chapter>
	
	<title>&adminguide;</title>
	
	<section>
	<title>Overview</title>
	<para>
		 The pua_mi offers the possibility to publish presence
	         information and subscribe to presence information via MI
 	         transports.
	</para>
	<para>
		Using this module you can create independent applications/scripts to
		publish not sip-related information (e.g., system resources like
		CPU-usage, memory, number of active subscribers ...).
	        Also, this module allows non-SIP speaking applications
		to subscribe presence information kept in a SIP presence
	        server.
	</para>
	<para>
	</para>
	</section>

	<section>
	<title>Dependencies</title>
	<section>
		<title>&kamailio; Modules</title>
		<para>
		The following modules must be loaded before this module:
		</para>
			<itemizedlist>
			<listitem>
			<para>
				<emphasis>pua</emphasis>
			</para>
			</listitem>
			</itemizedlist>
	</section>
	
	<section>
		<title>External Libraries or Applications</title>
		<para>
		The following libraries or applications must be installed before running
		&kamailio; with this module loaded:
		</para>
			<itemizedlist>
			<listitem>
			<para>
				<emphasis>none</emphasis>
			</para>
			</listitem>
			</itemizedlist>
	</section>
	</section>
	
	<section>
		<title>Parameters</title>
		<itemizedlist>
			<listitem>
			<para>
				<emphasis>none</emphasis>
			</para>
			</listitem>
		</itemizedlist>	
	</section>	

	<section>
		<title>Functions</title>
		<para>The module does not export functions to be used
		in configuration script.</para>
	</section>	
	<section>
		<title>Exported MI functions</title>
		<section>
				<title>
				<function moreinfo="none">pua_publish</function>
				</title>
			<para>
				Command parameters:
			</para>
			<itemizedlist>
			<listitem>
				<para>
					<emphasis>presentity_uri</emphasis>
					- e.g. sip:system@kamailio.org
				</para>	
			</listitem>
			<listitem>
				<para>
					<emphasis>expires</emphasis>
					- Relative expires time in
					seconds (e.g. 3600).
				</para>	
			</listitem>
			<listitem>
				<para>
					<emphasis>event package</emphasis>
					- Event package that is
		target of published information (e.g. presence).
				    </para> 
			</listitem>
			<listitem>
				<para>
					<emphasis>content type</emphasis>
					- Content type of published
		information (e.g. application/pidf+xml) or . if no
		information is enclosed.
			       </para> 
			</listitem>
			<listitem>
				<para>
					<emphasis>id</emphasis>
					- id for a series of related PUBLISHes to the same 
		presentity-uri or . to always use the same series.
		For example dialog-info must reuse the same id for the
		same call otherwise status will be lost when multiple
		parallel calls to/from the same user take place. The
		dialog-id from the dialog-info body qualifies as a suitable
		id here.
		                </para> 
			</listitem>
			<listitem>
				<para>
					<emphasis>ETag</emphasis>
					- ETag that publish should
		match or . if no ETag is given.
		                </para> 
			</listitem>
			<listitem>
				<para>
					<emphasis>extra_headers</emphasis>
					- Extra headers added to PUBLISH
		request or . if no extra headers.
		                </para> 
			</listitem>
			<listitem>
				<para>
					<emphasis>body</emphasis>
					- The body of the publish
		request containing published information or missing if
		no published information.
		It has to be a single line for FIFO transport.
				 </para>
			</listitem>
			</itemizedlist>
		<example>
		<title><function>pua_publish</function> FIFO example</title>
	<programlisting format="linespecific">
...
<![CDATA[
:pua_publish:fifo_test_reply
sip:system@kamailio.org
3600
presence
application/pidf+xml
.
.
.
<?xml version='1.0'?><presence xmlns='urn:ietf:params:xml:ns:pidf' xmlns:dm='urn:ietf:params:xml:ns:pidf:data-model' xmlns:rpid='urn:ietf:params:xml:ns:pidf:rpid' xmlns:c='urn:ietf:params:xml:ns:pidf:cipid' entity='system@kamailio.org'><tuple id='0x81475a0'><status><basic>open</basic></status></tuple><dm:person id='pdd748945'><rpid:activities><rpid:away/>away</rpid:activities><dm:note>CPU:16 MEM:476</dm:note></dm:person></presence>
]]>
</programlisting>
		</example>
		</section>

	</section>		
	<section>
		<title>
			<function moreinfo="none">pua_subscribe</function>
		</title>
		<para>
			Command parameters:
		</para>	
			<itemizedlist>
			<listitem>
				<para>
					<emphasis>presentity_uri</emphasis>
					- e.g. sip:presentity@kamailio.org
				</para>	
			</listitem>
			<listitem>
				<para>
					<emphasis>watcher_uri</emphasis>
					- e.g. sip:watcher@kamailio.org
				</para>	
			</listitem>

			<listitem>
				<para>
					<emphasis>event package</emphasis>
				</para>	
			</listitem>
			<listitem>
				<para>
					<emphasis>expires</emphasis>
					- Relative time in seconds for the desired validity of the subscription.
				    </para> 
			</listitem>	
			</itemizedlist>
	</section>
</chapter>