<?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>
	This module implements various utility functions that are not SIP
	related.
	</para>
	<para>
	Function http_query allows &kamailio; to issue an HTTP GET
	request and get access to parts of the reply.
	</para>
	<para>
	The forward functionality allows &kamailio; to configure forwarding
	at runtime with FIFO commands. The forwarding is executed in the pre
	script call back and therefore handled before the routing script is
	executed on the current message. The callback is not installed on
	default, thus this functionality has no runtime overhead when its
	deactivated.
	</para>
	<para>
	Function xcap_auth_status can be used to check from presence
	server database, if watcher is authorized to subscribe event
	<quote>presence</quote> of presentity.
	</para>
	</section>
	<section>
	<title>Dependencies</title>
	<section>
		<title>&kamailio; Modules</title>
		<para>
		The following modules must be loaded before this module:
			<itemizedlist>
			<listitem>
			<para>
				<emphasis>a database module if
	xcap_auth_status function is enabled</emphasis>.
			</para>
			</listitem>
			</itemizedlist>
		</para>
	</section>
	<section>
		<title>External Libraries or Applications</title>
		<para>
		The following libraries or applications must be
		installed before  
		running &kamailio; with this module loaded:
			<itemizedlist>
			<listitem>
			<para>
				<emphasis>libcurl</emphasis>.
			</para>
			</listitem>
			</itemizedlist>
		</para>
	</section>
	</section>
	
	<section>
		<title>Parameters</title>
		<section id="utils.p.http_query_timeout">
			<title><varname>http_query_timeout</varname> (int)</title>
			<para>
			Defines in seconds how long &kamailio; waits for response
			from HTTP server.
			</para>
			<para>
			<emphasis>
				Default value is zero, i.e.,
				that the http_query_timeout function is disabled.
			</emphasis>
			</para>
			<example>
			<title>Set <varname>http_query_timeout</varname> parameter</title>
				<programlisting format="linespecific">
...
modparam("utils", "http_query_timeout", 2)
...
				</programlisting>
			</example>
		</section>
		<section id="utils.p.forward_active">
			<title><varname>forward_active</varname> (int)</title>
			<para>
				Defines if the forwarding callback should be installed.
			</para>
			<para>
				<emphasis>
					Default value is <quote>0</quote> - disabled.
				</emphasis>
			</para>
			<example>
				<title>Set <varname>forward_active</varname> parameter</title>
				<programlisting format="linespecific">
					...
					modparam("utils", "forward_active", 1)
					...
				</programlisting>
			</example>
		</section>
		<section id="utils.p.pres_db_url">
			<title><varname>pres_db_url</varname> (string)</title>
			<para>
			Defines presence server database URL. If not
			given, the xcap_auth_status function is disabled.
			</para>
			<para>
			<emphasis>
				There is no default value.
			</emphasis>
			</para>
			<example>
			<title>Set <varname>pres_db_url</varname> parameter</title>
				<programlisting format="linespecific">
...
modparam("utils", "pres_db_url", "mysql://foo:secret@localhost/pres")
...
				</programlisting>
			</example>
		</section>
		<section id="utils.p.xcap_table">
			<title><varname>xcap_table</varname> (string)</title>
			<para>
			Defines the name of the xcap table in the presence server database.
			See the xcap_server module documentation for more information.
			</para>
			<para>
			<emphasis>
				Default value is <quote>xcap</quote>.
			</emphasis>
			</para>
			<example>
			<title>Set <varname>xcap_table</varname> parameter</title>
				<programlisting format="linespecific">
...
modparam("utils", "xcap_table", "pres_xcap")
...
				</programlisting>
			</example>
		</section>
	</section>

	<section>
	<title>Functions</title>
		<section id="utils.f.http_query">
			<title>
				<function moreinfo="none">http_query(url, [post-data], result)</function>
			</title>
			<para>
			Sends HTTP GET or POST request according to URL given in
			<quote>url</quote> parameter, which is a string that may
			contain pseudo variables.
	    	        </para>
			<para>
			If you want to make a POST-Request, you have to define
			the <quote>post</quote>-data, that should be submitted
			in that request as the second parameter.
	    	        </para>
		        <para>
			If HTTP server returns a class 2xx, 3xx or 4xx reply,
			the first line of the reply's body (if any) is
			stored in <quote>result</quote> parameter,
			which must be a	writable pseudo	variable.
			</para>
			<para>
			Function returns reply code of HTTP reply or -1
			if something went wrong.
	   	     	</para>
			<para>
			This function can be used from REQUEST_ROUTE,
			ONREPLY_ROUTE, FAILURE_ROUTE, and BRANCH_ROUTE.
			</para>
			<example>
				<title><function>http_query()</function> usage</title>
				<programlisting format="linespecific">
...
# GET-Request
http_query("http://tutpro.com/index.php?r_uri=$(ru{s.escape.param})&amp;f_uri=$(fu{s.escape.param})",
           "$var(result)")
switch ($retcode) {
       ...
}
...
				</programlisting>
				<programlisting format="linespecific">
...
# POST-Request
http_query("http://tutpro.com/index.php", "r_uri=$(ru{s.escape.param})&amp;f_uri=$(fu{s.escape.param})",
           "$var(result)")
switch ($retcode) {
       ...
}
...
				</programlisting>
			</example>
		</section>
		<section id="utils.f.xcap_auth_status">
			<title>
				<function moreinfo="none">xcap_auth_status(watcher_uri, presentity_uri)</function>
			</title>
			<para>
			Function checks in the presence server database if
			a watcher is authorized to subscribe to event
			<quote>presence</quote> of presentity.  Sphere
			checking is not included.
			</para>
			<para>
			Both watcher_uri and presentity_uri are
			pseudo variables. The function returns
			ACTIVE_STATUS, if a subscription is 
			allowed and PENDING_STATUS, TERMINATED_STATUS,
			or WAITING_STATUS otherwise. See
			presence/subscribe.h for the corresponding integer
			codes. In case of error, function returns -1.
	    	        </para>
			<para>
			Function can be used from REQUEST_ROUTE.
			</para>
			<example>
				<title><function>xcap_auth_status()</function> usage</title>
				<programlisting format="linespecific">
...
if (method=="MESSAGE") {
    xcap_auth_status("$fu", $ru");
    if ($retcode == 1) {
        t_relay();
    } else {
        send_reply("403", "Forbidden");
    }
}
...
				</programlisting>
			</example>
		</section>
	</section>
	
	<section>
	    <title><acronym>MI</acronym> Commands</title>
		
	<section id="utils.m.forward_list">
	    <title><function moreinfo="none">forward_list</function></title>
	    <para>
		List active forward rules.
	    </para>
		<para>
		No parameters.
		</para>
	    <example>
		<title><function>forward_list</function> usage</title>
		<programlisting format="linespecific">
...
&ctltool; fifo forward_list
id switch                         filter proxy
 0    off      REGISTER:INVITE:SUBSCRIBE host-a.domain-a:5060
...
		</programlisting>
	    </example>
	</section>
	<section id="utils.m.forward_switch">
	    <title><function moreinfo="none">forward_switch</function></title>
	    <para>
		This command can be used to activate or deactivate forwarding rules.
		The syntax of this configuration string is described in 1.6. (switch_setting_list).
	    </para>
	    <example>
		<title><function>forward_switch</function> usage</title>
		<programlisting format="linespecific">
...
&ctltool; fifo forward_switch 0=on
...
		</programlisting>
	    </example>
	</section>
	<section id="utils.m.forward_filter">
	    <title><function moreinfo="none">forward_filter</function></title>
	    <para>
		Can be used to specify the filter for a certain id. Messages will only be
		forwarded if one of the filters matches the message.
		</para>
		<para>
		There are special filters and regular filters.
		Special filters are:
		<itemizedlist>
		<listitem>REQUEST (matches on every request)</listitem>
		<listitem>REPLY   (matches on every reply)</listitem>
		</itemizedlist>
		</para>
		<para>
		Regular filters are arbitrary strings not containing the
	 	delimiter ':'. They are matched against the request method
		names of the sip messages. The syntax of this configuration
		string is described in 1.6. (filter_setting_list).
	    </para>
	    <example>
		<title><function>forward_filter</function> usage</title>
		<programlisting format="linespecific">
...
&ctltool; fifo forward_filter 0=REGISTER:INVITE
...
		</programlisting>
	    </example>
	</section>
	<section id="utils.m.forward_proxy">
	    <title><function moreinfo="none">forward_proxy</function></title>
	    <para>
		This command can be used to configure forwarding rules. Specifies
		the destination for a certain id. Messages will be forwarded to
		this destination if the preconditions hold (matching id, filter, and
		switch). The syntax of this configuration string is described in 1.6.
		(proxy_setting_list).
	    </para>
	    <example>
		<title><function>forward_proxy</function> usage</title>
		<programlisting format="linespecific">
...
&ctltool; fifo forward_proxy 0=host-c.domain-c:5060
...
		</programlisting>
	    </example>
	</section>
	</section>
	
	<section>
		<title>Configuration syntax</title>
		<para>This grammar specify the usable configuration syntax</para>
		<itemizedlist>
			<listitem>switch_setting_list ::= switch_setting { "," switch_setting }</listitem>
			<listitem>filter_setting_list ::= switch_setting { "," switch_setting }</listitem>
			<listitem>proxy_setting_list  ::= proxy_setting  { "," proxy_setting  }</listitem>
			<listitem>switch_setting      ::= id "=" switch</listitem>
			<listitem>filter_setting      ::= id "=" filter_list</listitem>
			<listitem>proxy_setting       ::= id "=" proxy</listitem>
			<listitem>switch              ::= ( "off" | "on" )</listitem>
			<listitem>filter_list         ::= filter { ":" filter }</listitem>
			<listitem>proxy               ::= host ":" port</listitem>
			<listitem>filter              ::= ( special_filter | regular_filter )</listitem>
			<listitem>special_filter      ::= ( "REQUEST" | "REPLY" )</listitem>
			<listitem>regular_filter      ::= ? [^:]* ?</listitem>
			<listitem>host                ::= char { char }</listitem>
			<listitem>char                ::= ? A-Za-z0-9.-_ ?</listitem>
			<listitem>id                  ::= number</listitem>
			<listitem>port                ::= number</listitem>
			<listitem>number              ::= digit {digit}</listitem>
			<listitem>digit               ::= ? 0-9 ?</listitem>
		</itemizedlist>
	</section>
</chapter>