lost: adds HELD (RFC6155) and LOST (RFC5222) queries for location-based routing
authorwkampich <wolfgang.kampichler@gmail.com>
Wed, 14 Aug 2019 18:13:33 +0000 (20:13 +0200)
committerHenning Westerholt <hw@skalatan.de>
Fri, 16 Aug 2019 06:04:03 +0000 (08:04 +0200)
- code review, updates to memory managment and error handling

src/modules/lost/README [deleted file]

diff --git a/src/modules/lost/README b/src/modules/lost/README
deleted file mode 100644 (file)
index 9ea55a6..0000000
+++ /dev/null
@@ -1,238 +0,0 @@
-LOST Module
-
-Wolfgang Kampichler
-
-   Frequentis AG
-   DEC112 (funded by netidee)
-
-Edited by
-
-Wolfgang Kampichler
-
-   Copyright © 20018-2019 Wolfgang Kampichler
-     __________________________________________________________________
-
-   Table of Contents
-
-   1. Admin Guide
-
-        1. Overview
-        2. Dependencies
-
-              2.1. Kamailio Modules
-              2.2. External Libraries or Applications
-
-        3. Parameters
-        4. Functions
-
-              4.1. lost_held_query(con, [id,] pidf-lo, url, error)
-              4.2. lost_query(con, [pidf-lo, urn,] uri, name, error)
-
-        5. Counters
-        6. Remarks
-
-   List of Examples
-
-   1.1. lost_held_query() usage
-   1.2. lost() usage
-
-Chapter 1. Admin Guide
-
-   Table of Contents
-
-   1. Overview
-   2. Dependencies
-
-        2.1. Kamailio Modules
-        2.2. External Libraries or Applications
-
-   3. Parameters
-   4. Functions
-
-        4.1. lost_held_query(con, [id,] pidf-lo, url, error)
-        4.2. lost_query(con, [pidf-lo, urn,] uri, name, error)
-
-   5. Counters
-   6. Remarks
-
-1. Overview
-
-   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.
-
-   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.
-
-   The function lost_held_query allows Kamailio to assemble a HELD
-   locationRequest as defined in RFC6155
-   (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).
-
-   The function lost_query allows Kamailio to assemble a LOST findService
-   request as defined in RFC5222 (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.
-
-   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.
-
-   The module is limited to using HTTP and HTTPS protocols.
-
-2. Dependencies
-
-   2.1. Kamailio Modules
-   2.2. External Libraries or Applications
-
-2.1. Kamailio Modules
-
-   The following modules must be loaded before this module:
-     * HTTP_CLIENT - the http_client module should be loaded first in
-       order to initialize connections properly.
-     * TLS - if you use TLS connections (https) the tls module should be
-       loaded first in order to initialize OpenSSL properly.
-
-2.2. External Libraries or Applications
-
-   The following libraries or applications must be installed before
-   running Kamailio with this module loaded:
-     * libcurl
-     * libxml2
-
-3. Parameters
-
-   This module has no specific paramater but uses http_client therfore
-   according parameters may apply.
-
-4. Functions
-
-   4.1. lost_held_query(con, [id,] pidf-lo, url, error)
-   4.2. lost_query(con, [pidf-lo, urn,] uri, name, error)
-
-4.1.  lost_held_query(con, [id,] pidf-lo, url, error)
-
-   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.
-     * con - the name of an existing HTTP connection, definied by a
-       httpcon modparam
-     * id - the device id used in the HELD locationRequest
-     * pidf-lo - the PIDF-LO returned in the HELD locationRequest response
-     * url - the location reference returned in the HELD locationRequest
-       response - this reference may be added as Geolocation header value
-       and forwarded downstream
-     * error - any error code returned in the HELD locationRequest
-       response
-
-   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.
-
-   This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE,
-   FAILURE_ROUTE, and BRANCH_ROUTE.
-
-   Example 1.1. lost_held_query() usage
-...
-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$va
-r(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$va
-r(pidf)\n");
-...
-
-4.2.  lost_query(con, [pidf-lo, urn,] uri, name, error)
-
-   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.
-     * con - the name of an existing HTTP connection definied by a httpcon
-       modparam
-     * pidf-lo - the PIDF-LO used to create the LOST findService request
-     * urn - the URN used to create the LOST findService request
-     * uri - the SIP uri returned in the LOST findServiceResponse
-     * name - the display name returned in the LOST findServiceResponse
-     * error - any error code returned in the LOST findServiceResponse
-
-   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.
-
-   This function can be used from REQUEST_ROUTE, ONREPLY_ROUTE,
-   FAILURE_ROUTE, and BRANCH_ROUTE.
-
-   Example 1.2. lost() usage
-...
-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");
-...
-
-5. Counters
-
-   This module has no specific counters but uses http_client therfore
-   according counters may apply.
-
-6. Remarks
-
-   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:
-   https://www.digitalocean.com/community/questions/how-to-upgrade-curl-in
-   -centos6
-
-   Note: http_client_query exported by the http_client API returns 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.