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

<chapter>
	
	<title>&adminguide;</title>
	
	<section id="overview" xreflabel="Overview">
	<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 id="dependencies" xreflabel="Dependencies">
	<title>Dependencies</title>
	<section>
		<title>&osips; 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
		&osips; with this module loaded:
		</para>
			<itemizedlist>
			<listitem>
			<para>
				<emphasis>none</emphasis>
			</para>
			</listitem>
			</itemizedlist>
	</section>
	</section>
	
	<section id="exported_parameters" xreflabel="Exported Parameters">
		<title>Exported Parameters</title>
		<section id="param_presence_server" xreflabel="presence_server">
		<title><varname>presence_server</varname> (str)</title>
		<para>
		The the address of the presence server. If set, it will be
		used as outbound proxy when sending PUBLISH requests.
		</para>
		<example>
		<title>Set <varname>presence_server</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("pua_mi", "presence_server", "sip:pa@opensips.org:5075")
...
	</programlisting>
		</example>
	</section>
</section>	

	<section id="exported_functions" xreflabel="exported_functions">
		<title>Exported Functions</title>
		<para>The module does not export functions to be used
		in configuration script.</para>
	</section>	
	<section id="exported_mi_functions" xreflabel="Exported MI Functions">
		<title>Exported MI functions</title>
		<section id="mi_pua_publish" xreflabel="pua_publish">
				<title>
				<function moreinfo="none">pua_publish</function>
				</title>
			<para>
				Command parameters:
			</para>
			<itemizedlist>
			<listitem>
				<para>
					<emphasis>presentity_uri</emphasis>
					- e.g. sip:system@opensips.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> (optional)
					- Content type of published
		information (e.g. application/pidf+xml). If this parameter
		is provided, the <emphasis>body</emphasis> parameter is also required.
			       </para> 
			</listitem>
			<listitem>
				<para>
					<emphasis>etag</emphasis> (optional)
					- ETag that publish should
		match.
		                </para> 
			</listitem>
			<listitem>
				<para>
					<emphasis>extra_headers</emphasis> (optional)
					- Extra headers added to PUBLISH
		request.
		                </para> 
			</listitem>
			<listitem>
				<para>
					<emphasis>body</emphasis> (optioanl)
					- 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. If this parameter
		is provided, the <emphasis>content_type</emphasis> parameter is also required.
				 </para>
			</listitem>
			</itemizedlist>
		<example>
		<title><function>pua_publish</function> FIFO example</title>
	<programlisting format="linespecific">
...
<![CDATA[
opensips-cli -x mi pua_publish sip:system@opensips.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@opensips.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 id="mi_pua_subscribe" xreflabel="pua_subscribe">
		<title>
			<function moreinfo="none">pua_subscribe</function>
		</title>
		<para>
			Command parameters:
		</para>	
			<itemizedlist>
			<listitem>
				<para>
					<emphasis>presentity_uri</emphasis>
					- e.g. sip:presentity@opensips.org
				</para>	
			</listitem>
			<listitem>
				<para>
					<emphasis>watcher_uri</emphasis>
					- e.g. sip:watcher@opensips.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>
		<example>
		<title><function>pua_subscribe</function> FIFO example</title>
	<programlisting format="linespecific">
...
<![CDATA[
opensips-cli -x mi pua_subscribe sip:system@opensips.org sip:400@opensips.org presence 3600
]]>
</programlisting>
		</example>
	</section>
</section>
</chapter>

