<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
   "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">

<chapter>
	<title>Admin Guide</title>
    <section id="xmlops.overview">
	<title>Overview</title>
	<para>
		This is a module implementing functions and pseudo-variables for
		XML operations.
	</para>
    </section>
	<section id="xmlops.deps">
	<title>Dependencies</title>
		<section>
		<title>Kamailio Modules</title>
			<para>
			The following modules must be loaded before this module:
			</para>
			<itemizedlist>
			<listitem>
			<para>
				<emphasis>none</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>libxml</emphasis> - for compilation from source, the
				development headers from this library are needed as well.
			</para>
			</listitem>
			</itemizedlist>
		</section>
    </section>

<section id="xmlops.parameters" xmlns:xi="http://www.w3.org/2001/XInclude">
    <title>Parameters</title>

    <section id="xmlops.p.buf_size">
	<title><varname>buf_size</varname> (integer)</title>
	<para>
	    Maximum size of the XML buffer.
	</para>
	<para>
	    Default value is 4096.
	</para>
	<example>
	    <title>Set <varname>buf_size</varname> parameter</title>
	    <programlisting>
...
modparam("xmlops", "buf_size", 8192)
...
	    </programlisting>
	</example>
    </section>

	<section id="xmlops.p.xml_ns">
		<title><varname>xml_ns</varname> (str)</title>
		<para>
		Register xml namespace prefix. Parameter value must have the format:
		'prefix=uri'. It can be set many times to cope with multiple namespaces
		without prefix.
		</para>
		<para>
		This is useful when it is needed to access XML documents that specify
		xmlns without prefix, which is not XML-standard compliant, but it
		comes with SIP SIMPLE presence bodies.
		</para>
		<example>
		<title>Set <varname>xml_ns</varname> parameter</title>
		<programlisting format="linespecific">
<![CDATA[
...
modparam("xmlops", "xml_ns", "rpid=urn:ietf:params:xml:ns:pidf:rpid")
modparam("xmlops", "xml_ns", "pidf=urn:ietf:params:xml:ns:pidf")
...
$xml(x=>doc) = '<?xml version="1.0" encoding="utf-8"?>
    <presence xmlns="urn:ietf:params:xml:ns:pidf" entity="sip:test@mydomain.com">
        <tuple id="86ae65b7-42de-4399-b635-295caad13aac">
            <status><basic>none</basic></status>
        </tuple>
    </presence>';

xinfo("status: $xml(x=>xpath:/pidf:presence/pidf:tuple/pidf:status/pidf:basic)\n");
...
]]>
</programlisting>
		</example>
	</section>
</section>

<section id="xmlops.pvs">
    <title>Pseudo-Variables</title>
	<section>
		<title>
		<function moreinfo="none">$xml(name=>spec)</function>
		</title>
		<para>
		Pseudo-variable for XML document operations using xpath syntax. For
		more see the Pseudo-Variables Cookbook.
		</para>
		<example>
		<title><function>xml</function> usage</title>
		<programlisting format="linespecific">
...
$xml(x=&gt;doc)
    = '&lt;?xml version="1.0" encoding="UTF-8"?&gt;&lt;a&gt;&lt;b&gt;test&lt;/b&gt;&lt;/a&gt;';
xlog("content of node b: $xml(x=&gt;xpath:/a/b/text())\n");
$xml(x=&gt;xpath:/a/b) = "1234";
...
</programlisting>
		</example>
	</section>
</section>
</chapter>
