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

<chapter>
	
	<title>&adminguide;</title>
	
	<section id="overview" xreflabel="Overview">
	<title>Overview</title>
	<para> 
	The modules is an XCAP client for OpenSIPS that can be used by other modules.
	It fetches XCAP elements, either documents or part of them, by sending 
	HTTP GET requests. It also offers support for conditional queries.
	It uses libcurl library as a client-side HTTP transfer library.
	</para>
	<para>
	The module offers an xcap client interface with general functions that
	allow requesting for an specific element from an xcap server.
	In addition to that it also offers the service of storing and update
	in database the documents it receives. In this case only an initial
	request to the module is required - xcapGetNewDoc-which is like a 
	request to the module to handle from that point on the referenced
	document so as to promise that the newest version will always be
	present in database.
	</para>
	<para>
	The update method is also configurable, 
	either through periodical queries, applicable to any kind of xcap
	server or with an MI command that should be sent by the server
	upon an update.
	</para>
	<para>
	The module is currently used by the presence_xml module, if the 
	'integrated_xcap_server' parameter is not set.
	</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:
			<itemizedlist>
			<listitem>
			<para>
				<emphasis>xcap</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>libxml-dev</emphasis>.
			</para>
			</listitem>
			<listitem>
			<para>
				<emphasis>libcurl-dev</emphasis>.
			</para>
			</listitem>
			</itemizedlist>
		</para>
	</section>
	</section>

	<section id="exported_parameters" xreflabel="Exported Parameters">
	<title>Exported Parameters</title>
	<section id="param_periodical_query" xreflabel="periodical_query">
		<title><varname>periodical_query</varname>(int)</title>
		<para>
		A flag to disable periodical query as an update method for
		the documents the module is responsible for. It could be
		disabled when the xcap server is capable to send the exported
		MI command when a change occurs or when another module in &osips;
		handles updates.
		</para>
		<para>
		To disable it set this parameter to 0.
		</para>
		<para>
		<emphasis>	Default value is <quote>1</quote>.
		</emphasis>
		</para>
		<example>
		<title>Set <varname>periodical_query</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("xcap_client", "periodical_query", 0)
...
</programlisting>
		</example>
	</section>
	<section id="param_query_period" xreflabel="query_period">
		<title><varname>query_period</varname>(int)</title>
		<para>
		Should be set if periodical query is not disabled. 
		Represents the time interval the xcap servers should be 
		queried for an update
		</para>
		<para>
		To disable it set this parameter to 0.
		</para>
		<para>
		<emphasis>	Default value is <quote>100</quote>.
		</emphasis>
		</para>
		<example>
		<title>Set <varname>query_period</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("xcap_client", "query_period", 50)
...
</programlisting>
		</example>
	</section>
	</section>

<section id="exported_functions" xreflabel="exported_functions">
	<title>Exported Functions</title>
	<para>
	None to be used in configuration file.
	</para>
</section>

<section id="exported_mi_functions" xreflabel="Exported MI Functions">
	<title>Exported MI Functions</title>
	<section id="mi_refreshXcapDoc" xreflabel="refreshXcapDoc">
		<title>
		<function moreinfo="none">refreshXcapDoc</function>
		</title>
		<para>
		MI command that should be sent by an xcap server when a
		stored document changes.
		</para>
		<para>
		Name: <emphasis>refreshXcapDoc</emphasis>
		</para>
		<para>Parameters:</para>
		<itemizedlist>
			<listitem>
				<para>doc_uri: the uri of the document</para>
			</listitem>
			<listitem>
				<para>port: the port of the xcap server</para>
			</listitem>
		 </itemizedlist>

        <para>
		MI FIFO Command Format:
		</para>
        <programlisting  format="linespecific">
...
opensips-cli -x mi refreshXcapDoc /xcap-root/resource-lists/users/eyebeam/buddies-resource-list.xml 8000
...
		</programlisting>
	</section>

   	</section>

</chapter>

