kamailio/modules/utils/doc/utils_admin.xml

<?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>Exported Parameters</title>
		<section>
			<title><varname>http_query_timeout</varname> (int)</title>
			<para>
			Defines in seconds how long &kamailio; waits response
			from HTTP server.
			</para>
			<para>
			<emphasis>
				Default value is null, i.e.,
				xcap_auth_status 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>
			<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>.
				</emphasis>
			</para>
			<example>
				<title>Set <varname>forward_active</varname> parameter</title>
				<programlisting format="linespecific">
					...
					modparam("utils", "forward_active", 1)
					...
				</programlisting>
			</example>
		</section>
		<section>
			<title><varname>pres_db_url</varname> (string)</title>
			<para>
			Defines presence server database URL.  If not
			given, 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>
			<title><varname>xcap_table</varname> (string)</title>
			<para>
			Defines name of xcap table in presence server database.
			</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>Exported Functions</title>
		<section>
			<title>
				<function moreinfo="none">http_query(url, result)</function>
			</title>
			<para>
			Sends HTTP GET request according to URL given in
			<quote>url</quote> parameter, which is a string that may
			contain pseudo variables.
	    	        </para>
		        <para>
			If HTTP server returns a class 2xx or 3xx reply,
			first line of 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">
...
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>
			<title>
				<function moreinfo="none">xcap_auth_status(watcher_uri, presentity_uri)</function>
			</title>
			<para>
			Function checks from presence server database if
			watcher is authorized to subscribe event
			<quote>presence</quote> of presentity.  Sphere
			checking is not included.
			</para>
			<para>
			Both watcher_uri and presentity_uri are
			pseudo variables. Function returns
			ACTIVE_STATUS, if 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>
	    <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">
...
kamctl fifo forward_list
id switch                         filter proxy
 0    off      REGISTER:INVITE:SUBSCRIBE host-a.domain-a:5060
...
		</programlisting>
	    </example>
		</section>
		<section>
	    <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">
...
kamctl fifo sp_forward_switch 0=on
...
		</programlisting>
	    </example>
		</section>
		
		<section>
	    <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">
...
kamctl fifo sp_forward_filter 0=REGISTER:INVITE
...
		</programlisting>
	    </example>
		</section>

		<section>
	    <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">
...
kamctl fifo sp_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>