<?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 "../../../../doc/docbook/entities.xml">
%docentities;

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

<chapter>
	<title>&adminguide;</title>
	<section>
        <title>Overview</title>
        <para>
        SIP requests may be forwarded based on a location provided with the
        request or retrieved from a specific location server using an identity
        (HELD). This module implements the basic functionality to get or parse
        location information and to query a mapping service (LOST) in order to
        get next hop based on location and service urn either specified or
        provided with the request. 
        </para>
        <para>
        This module implements protocol functions that use the http_client api
        to fetch data from external LOST and HELD servers. The module is using
        the http_client concept of "connections" to define properties of HTTP
        sessions. A connection has one or multiple servers and a set of settings
        that apply to the specific connection.
        </para>
        <para>
        The function lost_held_query allows &kamailio; to assemble a HELD
        locationRequest as defined in RFC6155
        (<ulink url="https://tools.ietf.org/html/rfc6155"/>) to query location
        information represented as PIDF-LO for a given identity (in most cases
        a SIP URI). The identity may be a specific parameter or taken from the
        P-Asserted-Identity or From header. The locationRequest response is
        parsed and represented as PIDF-LO and location URI to dereference
        location via HTTP(S).
        </para>
        <para>
        The function lost_query allows &kamailio; to assemble a LOST
        findService request  as defined in RFC5222
        (<ulink url="https://tools.ietf.org/html/rfc5255"/>) to query 
        routing information for a given (geodetic) location and a service
        URN. Both, PIDF-LO and service URN may be provided as function parameter,
        or are taken from the request message if applicable. The findServiceResponse
        is parsed and represented asdisplay name and SIP URI typically used as next
        hop in a Route header.
        </para>
        <para>
        The http_client module use the CURL library setting up connections.
        The CURL library by default use the system configured DNS resolvers,
        not the Kamailio resolver.
        </para>
        <para>
        The module is limited to using HTTP and HTTPS protocols.
        </para>
	</section>
	<section>
	    <title>Dependencies</title>
	    <section>
		    <title>&kamailio; Modules</title>
		    <para>
		        The following modules must be loaded before this module:
                <itemizedlist>
                <listitem><para>
                HTTP_CLIENT - the http_client module should be
                loaded first in order to initialize connections properly.
                </para></listitem>
                <listitem><para>
                TLS - if you use TLS connections (https) the tls module should be
                loaded first in order to initialize &openssl; properly.
                </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>
                <listitem>
                <para>
                    <emphasis>libxml2</emphasis>
                </para>
                </listitem>
                </itemizedlist>
            </para>
        </section>
	</section>
	<section id="lost.p.general">
		<title>Parameters</title>
        <para>
        This module has no specific paramater but uses <emphasis>http_client</emphasis> therfore according
        parameters may apply.
        </para>
	</section>
	<section>
	    <title>Functions</title>
		<section id="lost.f.lost_held_query">
			<title>
				<function moreinfo="none">lost_held_query(con, [id,] pidf-lo, url, error)</function>
			</title>
			<para>
			Sends a HELD locationRequest to a given connection. The device identity is either specified,
            or the P-A-I header value, or the From header value.
	    	</para>
			    <itemizedlist>
				    <listitem><para>
						<emphasis>con</emphasis> - the name of an existing
						HTTP connection, definied by a httpcon modparam
				    </para></listitem>
                    <listitem><para>
						<emphasis>id</emphasis> - the device id used in the HELD
                        locationRequest
                    </para></listitem>
                    <listitem><para>
						<emphasis>pidf-lo</emphasis> - the PIDF-LO returned in the
                        HELD locationRequest response
                    </para></listitem>
                    <listitem><para>
						<emphasis>url</emphasis> - the location reference returned
                        in the HELD locationRequest response - this reference may be
                        added as Geolocation header value and forwarded downstream
                    </para></listitem>
                    <listitem><para>
						<emphasis>error</emphasis> - any error code returned in the
                        HELD locationRequest response
                    </para></listitem>
			    </itemizedlist>
			<para>
			The return value is 200 on success, 400 if an internal error occured, or 500 if an
            error code is returned in the HELD locationRequest response.
	    	</para>
			<para>
			This function can be used from REQUEST_ROUTE,
			ONREPLY_ROUTE, FAILURE_ROUTE, and BRANCH_ROUTE.
			</para>
			<example>
				<title><function>lost_held_query()</function> usage</title>
				<programlisting format="linespecific">
...
modparam("http_client", "httpcon", "heldsrv=>http://service.org/api/held");
...
# HELD location request
$var(id) = "sip:alice@atlanta";
$var(res) = lost_held_query("heldsrv", "$var(id)" , "$var(pidf)", "$var(url)", "$var(err)");
xlog("L_INFO", "HELD locationRequest: Result code $var(res)\nUrl: $var(url)\n$var(pidf)");
...
$var(res) = lost_held_query("heldsrv", "$var(pidf)", "$var(url)", "$var(err)");
xlog("L_INFO", "HELD locationRequest: Result code $var(res)\nUrl: $var(url)\n$var(pidf)\n");
...
				</programlisting>
			</example>
		</section>
		<section id="lost.f.lost_query">
			<title>
				<function moreinfo="none">lost_query(con, [pidf-lo, urn,] uri, name, error)</function>
			</title>
			<para>
			Sends a LOST findService request to a given connection. PIDF-LO and URN are either specified,
            or, if omitted, parsed from the message body (PIDF-LO) and request line (URN). Either "pidf-lo"
            or "urn" can be set to an empty string in order to be ignored. 
	    	</para>
			<itemizedlist>
                <listitem><para>
                    <emphasis>con</emphasis> - the name of an existing
                    HTTP connection definied by a httpcon modparam
                </para></listitem>
                <listitem><para>
                    <emphasis>pidf-lo</emphasis> - the PIDF-LO used to create the
                    LOST findService request
                </para></listitem>
                <listitem><para>
                    <emphasis>urn</emphasis> - the URN used to create the
                    LOST findService request
                </para></listitem>
                <listitem><para>
                    <emphasis>uri</emphasis> - the SIP uri returned in the
                    LOST findServiceResponse
                </para></listitem>
                <listitem><para>
                    <emphasis>name</emphasis> - the display name returned in the
                    LOST findServiceResponse
                </para></listitem>
                <listitem><para>
                    <emphasis>error</emphasis> - any error code returned in the
                    LOST findServiceResponse
                </para></listitem>
			</itemizedlist>
			<para>
			The return value is 200 on success, 400 if an internal error occured, or 500 if an
            error code is returned in the LOST findServiceResponse.
	    	</para>
			<para>
			This function can be used from REQUEST_ROUTE,
			ONREPLY_ROUTE, FAILURE_ROUTE, and BRANCH_ROUTE.
			</para>
			<example>
				<title><function>lost()</function> usage</title>
				<programlisting format="linespecific">
...
modparam("http_client", "httpcon", "heldsrv=>http://service.org/api/held");
modparam("http_client", "httpcon", "lostsrv=>http://service.org/api/lost");
...
# HELD location request
$var(id) = "sip:alice@atlanta";
$var(res) = lost_held_query("heldsrv", "$var(id)" , "$var(pidf)", "$var(url)", "$var(err)");
...
# LOST findService request - pidf-lo and urn as parameter
$var(id) = "urn:service:sos";
$var(res) = lost_query("lostsrv", "$var(pidf)", "$var(urn)", "$var(uri)", "$var(name)", "$var(err)");
xlog("L_INFO", "LOST findService: Result code $var(res)\nUri: $var(uri)\nName: $var(uri)\n");
...
# LOST findService request - pidf-lo as parameter, urn taken from request line
$var(res) = lost_query("lostsrv", "$var(pidf)", "", "$var(uri)", "$var(name)", "$var(err)");
xlog("L_INFO", "LOST findService: Result code $var(res)\nUri: $var(uri)\nName: $var(uri)\n");
...
# LOST findService request - urn as parameter, pidf-lo taken from message body
$var(res) = lost_query("lostsrv", "", "$var(urn)", "$var(uri)", "$var(name)", "$var(err)");
xlog("L_INFO", "LOST findService: Result code $var(res)\nUri: $var(uri)\nName: $var(uri)\n");
...
# LOST findService request - pidf-lo and urn taken from message
$var(res) = lost_query("lostsrv", "$var(uri)", "$var(name)", "$var(err)");
xlog("L_INFO", "LOST findService: Result code $var(res)\nUri: $var(uri)\nName: $var(uri)\n");
...
				</programlisting>
			</example>
		</section>

    </section>
    <section id="lost.s.counters">
	    <title>Counters</title>
        <para>
            This module has no specific counters but uses http_client therefore
            according counters may apply.
        </para>
	</section>

    <section id="lost.s.remarks">
        <title>Remarks</title>
        <para>
            Note: libcurl leak in CentOS 6 - this module uses libcurl library
            (via http_client) and in case if you are using CentOS 6, be aware that
            standard libcurl-7.19.7-52 has a memory leak. To fix this memory, install
            libcurl from city-fan repository. More details at:
            <ulink url="https://www.digitalocean.com/community/questions/how-to-upgrade-curl-in-centos6">
            https://www.digitalocean.com/community/questions/how-to-upgrade-curl-in-centos6</ulink>
        </para>
        <para>
            Note: http_client_query exported by the http_client API returns by default the first line of
            the HTTP response (query_params.oneline = 1), but the lost module requires the complete
            response message, which requires query_params.oneline set to 0. In the case lost_query
            is used with the default http_client API, dereferencing location via HTTP provided with
			the Geolocation header causes an error. Therefore, to work properlu=y, it requires to set
			<ulink url="https://www.kamailio.org/docs/modules/devel/modules/http_client.html#http_client.p.query_result">
			http_client module parameter query_result to 0</ulink>.
        </para>
    </section>
</chapter>
