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

<chapter>

    <title>&develguide;</title>
	<para>
            The module exports a number of parameters and functions that are used
            in several other modules.
   </para>
   <section>
      <title>
	     <function moreinfo="none">bind_xcap_api(xcap_api_t* api)</function>
     </title>
		<para>
		This function allows binding the needed functions.
		</para>
			<example>
			<title><function>xcap_api</function> structure</title>
			<programlisting format="linespecific">
...
typedef struct xcap_api {
        int integrated_server;
        str db_url;
        str xcap_table;
        normalize_sip_uri_t normalize_sip_uri;
        parse_xcap_uri_t parse_xcap_uri;
        get_xcap_doc_t get_xcap_doc;
} xcap_api_t;
...
			</programlisting>
			</example>
	</section>

	<section>
		<title>
			<function moreinfo="none">normalize_xcap_uri</function>
		</title>
		<para>
                    This function normalizes a SIP URI found in a XCAP document. It un-escapes it and
                    adds the SIP scheme in case it was missing. Returns a statically allocated string
                    buffer containing the normalized form.
		</para>
		<para>
		Parameters:
		</para>
			<itemizedlist>
			<listitem>
			<para>
				<emphasis>uri</emphasis>-
				the URI that needs to be normalized
			</para>
			</listitem>
		        </itemizedlist>
	</section>

	<section>
		<title>
			<function moreinfo="none">parse_xcap_uri</function>
		</title>
		<para>
			This function parses the given XCAP URI.
		</para>
		<para>
		Parameters:
		</para>
			<itemizedlist>
			<listitem>
			<para>
				<emphasis>uri</emphasis>-
				the URI that needs to be parsed in string format
			</para>
			</listitem>
			<listitem>
			<para>
				<emphasis>xcap_uri</emphasis>-
				xcap_uri_t structure that will be filled with the parsed information
			</para>
			<programlisting format="linespecific">
Parameter type:
...
typedef struct {
    char buf[MAX_URI_SIZE];
    str uri;
    str root;
    str auid;
    str tree;
    str xui;
    str filename;
    str selector;
} xcap_uri_t;
...
                        </programlisting>
                        </listitem>
		        </itemizedlist>
	</section>

	<section>
		<title>
			<function moreinfo="none">get_xcap_doc</function>
		</title>
		<para>
                    This function queries the local DB for the required XCAP document. It will return the document and its
                    corresponding etag.
		</para>
		<para>
		Parameters:
		</para>
			<itemizedlist>
			<listitem>
			<para>
				<emphasis>user</emphasis>-
				user part od the URI of the document owner
			</para>
			</listitem>
			<listitem>
			<para>
				<emphasis>domain</emphasis>-
				domain part od the URI of the document owner
			</para>
			</listitem>
			<listitem>
			<para>
				<emphasis>type</emphasis>-
                                type of the requested document, represents the AUID, can be one of PRES_RULES, RESOURCE_LISTS,
                                RLS_SERVICES, PIDF_MANIPULATION, OMA_PRES_RULES

			</para>
			</listitem>
			<listitem>
			<para>
				<emphasis>filename</emphasis>-
				if specified it will be used to match the document filename, it defaults to 'index'
			</para>
			</listitem>
			<listitem>
			<para>
				<emphasis>match_etag</emphasis>-
				if specified the document is only returned its etag matches this one
			</para>
			</listitem>
			<listitem>
			<para>
				<emphasis>doc</emphasis>-
				reference to the storage for the returned document
			</para>
			</listitem>
			<listitem>
			<para>
				<emphasis>etag</emphasis>-
				reference to the storage for the returned document's etag
			</para>
			</listitem>
		        </itemizedlist>
	</section>

        <section>
		<title>
			<parameter moreinfo="none">db_url</parameter>
		</title>
                <para>
                URL of the database to which the XCAP mdoules witll connect.
                </para>
	</section>

        <section>
		<title>
			<parameter moreinfo="none">xcap_table</parameter>
		</title>
                <para>
                Name of the table used to store XCAP documents. Defaults to 'xcap'.
                </para>
	</section>

        <section>
		<title>
			<parameter moreinfo="none">integrated_server</parameter>
		</title>
                <para>
                Boolean flag indicating if the XCAP server has access to the local database or
                xcap_client will be used to fetch documents.
                </para>
	</section>

</chapter>

