<?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>
	This module implements protocol functions that use the libcurl library
	to fetch data from external HTTP servers or post data to HTTP servers.
	The module is using a concept of "connections" to define properties
	of HTTP sessions in a simple way. A connection has one or multiple
	servers and a set of settings that apply to the specific connection.
	</para>
	<para>
	The http_client module has multiple settings, some of them apply to
	a defined connection. You can set timeouts, max data sizes for download
	and much more either using modparam settings or parameters to the
	connection definition.
	</para>
	<para>
	The connections can either be defined with the "httpcon" module parameter
	or in a separate configuration file, as specified by the "config_file" module
	parameter.
	</para>
	<para>
	Like in SIP, the HTTP URL may need encoding to be transported safely
	over the network. Check the string encoding functions in the Transformation
	Cookbook (as used in the http_client_query() example below).
	</para>
	<para>
	The function http_client_query() allows &kamailio; to issue an HTTP GET
	request and get access to parts of the reply. This function has
	been ported from the utils module and now use the same libcurl
	functions. We recommend using the new functionality provided by
	this module.
	</para>
	<para>
	The http_client module uses 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>
			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>
			</itemizedlist>
		</para>
	</section>
	</section>

	<section>
		<title>Parameters</title>
		<para>
		The parameters are loaded in order. That can lead to unexpected behavior:
		If httpcon is set at first, the default values for all other parameters are used,
		and not the values that might be set after httpcon.
		For example, if setting verify_peer=0 or verify_host=0 after httpcon,
		the certificates are checked and self-signed certificates are rejected nevertheless.
		</para>
		<section id="http_client.p.httpredirect">
			<title><varname>httpredirect</varname> (int)</title>
			<para>
			If set to 1, enabled, http_client will follow HTTP 302 Redirects.
			If set to 0, http_client will not follow redirects. Default is 1, enabled.
			</para>
			<para>
			The latest redirect URL will be stored in the <emphasis>$curlredirect</emphasis>
			pseudovariable.
			</para>
			<example>
			<title>Set <varname>httpredirect</varname> parameter</title>
				<programlisting format="linespecific">
...
modparam("http_client", "httpredirect", 0)
...
				</programlisting>
			</example>
		</section>
		<section id="http_client.p.httpproxy">
			<title><varname>httpproxy</varname> (string)</title>
			<para>
			URL for a HTTP proxy to use as a default proxy for all connections.
			</para>
			<para>
			This setting is also available on a per connection basis in the
			http_client configuration file.
			</para>
			<example>
			<title>Set <varname>httpproxy</varname> parameter</title>
				<programlisting format="linespecific">
...
modparam("http_client", "httpproxy", "https://superproxy.example.com")
...
				</programlisting>
			</example>
		</section>
		<section id="http_client.p.httpproxyport">
			<title><varname>httpproxyport</varname> (string)</title>
			<para>
			Port number for a HTTP proxy to use as a default proxy port for all connections.
			</para>
			<para>
			This setting is also available on a per connection basis in the
			http_client configuration file.
			</para>
			<example>
			<title>Set <varname>httpproxyport</varname> parameter</title>
				<programlisting format="linespecific">
...
modparam("http_client", "httpproxyport", 8042)
...
				</programlisting>
			</example>
		</section>
		<section id="http_client.p.useragent">
			<title><varname>useragent</varname> (string)</title>
			<para>
			Useragent to use in the HTTP protocol for requests. Defaults to
			the &kamailio; SIP useragent string - including software version and platform.
			</para>
			<example>
			<title>Set <varname>useragent</varname> parameter</title>
				<programlisting format="linespecific">
...
modparam("http_client", "useragent", "Secret HTTP REST grabber 0.42")
...
				</programlisting>
			</example>
		</section>
		<section id="http_client.p.maxdatasize">
			<title><varname>maxdatasize</varname> (int)</title>
			<para>
			Defines the maximum size in bytes for a response. Note that this
			is allocated from pkg memory (process memory) dynamically.
			</para>
			<para>
			<emphasis>
				Default value is zero, i.e.,
				the limit on the datasize is disabled.
			</emphasis>
			</para>
			<example>
			<title>Set <varname>maxdatasize</varname> parameter</title>
				<programlisting format="linespecific">
...
modparam("http_client", "maxdatasize", 2000)
...
				</programlisting>
			</example>
		</section>
		<section id="http_client.p.connection_timeout">
			<title><varname>connection_timeout</varname> (int)</title>
			<para>
			Defines in seconds how long &kamailio; waits for response
			from servers.
			</para>
			<para>
			<emphasis>
				Default value is zero, i.e.,
				the timeout function is disabled.
			</emphasis>
			</para>
			<example>
			<title>Set <varname>connection_timeout</varname> parameter</title>
				<programlisting format="linespecific">
...
modparam("http_client", "connection_timeout", 2)
...
				</programlisting>
			</example>
		</section>
		<section id="http_client.p.client_cert">
			<title><varname>client_cert</varname> (string)</title>
			<para>
			File name for a TLS client certificate. The certificate needs to be encoded
			in PEM format.
			</para>
			<para>
			<emphasis>
				Default value is empty string, i.e.
				no client certificate used. Note that if
				you specify a client cert, you also need to specify
				the <varname>client_key</varname>.
			</emphasis>
			</para>
			<example>
			<title>Set <varname>client_cert</varname> parameter</title>
				<programlisting format="linespecific">
...
modparam("http_client", "client_cert", "/var/certs/sollentuna.example.com.cert")
...
				</programlisting>
			</example>
		</section>
		<section id="http_client.p.client_key">
			<title><varname>client_key</varname> (string)</title>
			<para>
			File name for a TLS client key. The key needs to be encoded
			in PEM format.
			</para>
			<para>
			<emphasis>
				Default value is empty string, i.e.
				no client certificate or key is used. Note that if
				you specify a client key, you also need to specify
				the <varname>client_cert</varname>.
			</emphasis>
			</para>
			<example>
			<title>Set <varname>client_key</varname> parameter</title>
				<programlisting format="linespecific">
...
modparam("http_client", "client_key", "/var/certs/sollentuna.example.com.key")
...
				</programlisting>
			</example>
		</section>
		<section id="http_client.p.cacert">
			<title><varname>cacert</varname> (string)</title>
			<para>
			File name for the trusted TLS CA cert used to verify servers.
			The certificates need to be encoded in PEM format.
			</para>
			<para>
			<emphasis>
				Default value is empty string, i.e.
				no CA certificate is used to verify the host. If
				<varname>tlsverifyhost</varname> is on, all TLS
				connections will fail without any CA certificate
				to validate with.
			</emphasis>
			</para>
			<example>
			<title>Set <varname>cacert</varname> parameter</title>
				<programlisting format="linespecific">
...
modparam("http_client", "cacert", "/var/certs/ca/edvina-sip-ca.pem")
...
				</programlisting>
			</example>
		</section>
		<section id="http_client.p.cipher_suites">
			<title><varname>cipher_suites</varname> (string)</title>
			<para>
			List of allowed cipher suites.
			See http://curl.haxx.se/libcurl/c/CURLOPT_SSL_CIPHER_LIST.html for details
			of the cipher list curl option.
			</para>
			<para>
			<emphasis>
				Default value is empty string, i.e.
				the default list of ciphers in libcurl will be used.
			</emphasis>
			</para>
			<example>
			<title>Set <varname>cipher_suites</varname> parameter</title>
				<programlisting format="linespecific">
...
modparam("http_client", "cipher_suites", "ecdhe_ecdsa_aes_128_gcm_sha_256,rsa_aes_128_gcm_sha_256")
...
				</programlisting>
			</example>
		</section>
		<section id="http_client.p.verify_peer">
			<title><varname>verify_peer</varname> (int)</title>
			<para>
			If set to 0, TLS verification of the server certificate
			is disabled. This means that the connection will get
			encrypted, but there's no authentication. There's no
			proof that the transmission of data is to the host
			that is meant to receive data.
			</para>
			<para>
			If set to 1, default setting, and one or more CA certificates
			is configured, the server TLS certificate will be validated.
			If validation fails, the connection fails.
			</para>
			<para>
			See the curl documentation for more details.
			http://curl.haxx.se/libcurl/c/CURLOPT_SSL_VERIFYPEER.html
			</para>
			<example>
			<title>Set <varname>verify_peer</varname> parameter</title>
				<programlisting format="linespecific">
...
modparam("http_client", "verify_peer", 1)
...
				</programlisting>
			</example>
		</section>
		<section id="http_client.p.verify_host">
			<title><varname>verify_host</varname> (int)</title>
			<para>
			If set to 0, domain verification of the server certificate
			is disabled. This means that the connection will get
			encrypted but there is no check that data will be sent to the
			host that is meant to receive it. Disable with caution.
			</para>
			<para>
			If set to 2, default setting, the hostname in the URL will
			be verified against the Common Name or Subject Alt Name
			in the certificate. If validation fails, the connection fails.
			</para>
			<para>
			See the curl documentation for more details.
			http://curl.haxx.se/libcurl/c/CURLOPT_SSL_VERIFYHOST.html
			</para>
			<example>
			<title>Set <varname>verify_host</varname> parameter</title>
				<programlisting format="linespecific">
...
modparam("http_client", "verify_host", 2)
...
				</programlisting>
			</example>
		</section>
		<section id="http_client.p.tlsversion">
			<title><varname>tlsversion</varname> (int)</title>
			<para>
			Sets the preferred TLS/SSL version.
			</para>
			<para>
			Valid values are:
				<itemizedlist>
				<listitem><para>0 - Use libcurl default</para></listitem>
				<listitem><para>1 - "TLSv1"</para></listitem>
				<listitem><para>2 - "SSLv2"</para></listitem>
				<listitem><para>3 - "SSLv3"</para></listitem>
				<listitem><para>4 - "TLSv1.0"</para></listitem>
				<listitem><para>5 - "TLSv1.1"</para></listitem>
				<listitem><para>6 - "TLSv1.2"</para></listitem>
				</itemizedlist>
			</para>
			<para>
			SSL versions are now disabled by default.
			See the curl documentation for more details.
			http://curl.haxx.se/libcurl/c/CURLOPT_SSLVERSION.html
			</para>
			<example>
			<title>Set <varname>tlsversion</varname> parameter</title>
				<programlisting format="linespecific">
...
modparam("http_client", "tlsversion", 6)
...
				</programlisting>
			</example>
		</section>
		<section id="http_client.p.authmethod">
			<title><varname>authmethod</varname> (int)</title>
			<para>
			Sets the preferred authentication mode for HTTP/HTTPS requests. The value is a bitmap
			and multiple methods can be used. Note that in this case, the CURL library will make an
			extra request to discover server-supported authentication methods. You may want to use
			a specific value.
			</para>
			<para>
			Valid values are:
				<itemizedlist>
				<listitem><para>1 - BASIC authentication</para></listitem>
				<listitem><para>2 - HTTP Digest authentication</para></listitem>
				<listitem><para>4 - GSS-Negotiate authentication</para></listitem>
				<listitem><para>8 - NTLM authentication</para></listitem>
				<listitem><para>16 - HTTP Digest with IE flavour</para></listitem>
				</itemizedlist>
			Default value is 3 - BASIC and Digest authentication.
			</para>
			<para>
			This is also configurable per connection in the http_client configuration file.
			</para>
			<example>
			<title>Set <varname>authmethod</varname> parameter</title>
				<programlisting format="linespecific">
...
# Use the best of BASIC and Digest authentication.
modparam("http_client", "authmethod", 3)
...
				</programlisting>
			</example>
		</section>
		<section id="http_client.p.keep_connections">
			<title><varname>keep_connections</varname> (int)</title>
			<para>
			If an HTTP server is accessed multiple times keeping the connection open for reuse
			saves a significant amount of time, especially if TLS is used. If this function
			is enabled, the Curl library will try to reuse existing open connections. The
			HTTP server will have to support this feature and keep connections open for it
			to work properly.
			</para>
			<para>
			Valid values are:
				<itemizedlist>
				<listitem><para>0 - Close connections after request (default)</para></listitem>
				<listitem><para>1 - Reuse connections</para></listitem>
				</itemizedlist>
			</para>
			<para>
			This is also configurable per connection in the http_client configuration file.
			</para>
			<example>
			<title>Set <varname>keep_connections</varname> parameter</title>
				<programlisting format="linespecific">
...
modparam("http_client", "keep_connections", 1)
...
				</programlisting>
			</example>
		</section>
		<section id="http_client.p.query_result">
			<title><varname>query_result</varname> (int)</title>
			<para>
			Control what is returned by the http_client_query(...) in the result
			variable.
			</para>
			<para>
			Valid values are:
				<itemizedlist>
				<listitem><para>0 - Return the entire HTTP result body</para></listitem>
				<listitem><para>1 - Return the first line from HTTP result body</para></listitem>
				</itemizedlist>
			</para>
			<para>
			Default value: 1 (return first line).
			</para>
			<example>
			<title>Set <varname>query_result</varname> parameter</title>
				<programlisting format="linespecific">
...
modparam("http_client", "query_result", 0)
...
				</programlisting>
			</example>
		</section>
		<section id="http_client.p.query_maxdatasize">
			<title><varname>query_maxdatasize</varname> (int)</title>
			<para>
			Control the size in bytes of the data to be returned by the
			http_client_query(...) in the result variable.
			</para>
			<para>
			Default value: 0 (disabled, unlimited size).
			</para>
			<example>
			<title>Set <varname>query_maxdatasize</varname> parameter</title>
				<programlisting format="linespecific">
...
modparam("http_client", "query_maxdatasize", 2048)
...
				</programlisting>
			</example>
		</section>
		<section id="http_client.p.httpcon">
			<title><varname>httpcon</varname> (string)</title>
			<para>
			Defines a connection and credentials for the connection for use
			in a connection-oriented function call in this module.
			</para>
			<para>
			<emphasis>Syntax:</emphasis>
			&lt;connection-name&gt;=&gt;&lt;schema&gt;://[&lt;username&gt;:&lt;password&gt;@]&lt;hostname/address&gt;[;param=value]
			</para>
			<para>
			The address in the URL is the base for the URL in the <function>http_connect()</function> call. The
			address given in the function call will be appended to the base URL in the connection definition.
			</para>
			<para>
			The HTTP connection will be defined using default values in modparam's above the definition
			of the httpcon in the configuration file. Also note that connections can be defined in a
			separate text file if you have many parameters per connection, or want to use a per-connection
			setting that can be set in that file but not in the httpcon modparam, like authmethod.
			</para>
			<para>
			<emphasis>
				By default, no connections are defined.
			</emphasis>
			</para>
			<para>
			Parameters
			<itemizedlist>
				<listitem><para>
				<emphasis>useragent</emphasis> Useragent used for HTTP requests. Overrides
				useragent modparam.
				</para></listitem>
				<listitem><para>
				<emphasis>verify_peer</emphasis> Set to 1 to enable or 0 to disable server
				certificate verification.
				Overrides verify_peer modparam.
				</para></listitem>
				<listitem><para>
				<emphasis>verify_host</emphasis> Set to 2 to enable or 0 to disable server
				hostname verification.
				Overrides verify_host modparam.
				</para></listitem>
				<listitem><para>
				<emphasis>client_cert</emphasis> Client certificate used for this connection.
				Overrides the default client_cert modparam.
				</para></listitem>
				<listitem><para>
				<emphasis>client_key</emphasis> Client key used for this connection.
				Overrides the default client_key modparam.
				</para></listitem>
				<listitem><para>
				<emphasis>cipher_suites</emphasis> Client certificate used for this connection.
				Overrides the default cipher_suite modparam.
				</para></listitem>
				<listitem><para>
				<emphasis>timeout</emphasis> Timeout used for this connection. Overrides the
				default connection_timeout for the module.
				</para></listitem>
				<listitem><para>
				<emphasis>tlsversion</emphasis> TLS version used for this connection. Overrides the
				default tlsversion for the module.
				</para></listitem>
				<listitem><para>
				<emphasis>maxdatasize</emphasis> The maximum datasize for a response. Overrides
				the maxdatasize modparam setting.
				</para></listitem>
				<listitem><para>
				<emphasis>httpredirect</emphasis> Set to 1 for following HTTP 302
				redirect. 0 to disable. Overrides the default httpredirect modparam.
				</para></listitem>
				<listitem><para>
				<emphasis>failover</emphasis> The name of another <emphasis>httpcon</emphasis>
				connection to use with the same arguments in case a connection with this http_con fails.
				Failure is either a connection failure or a response code of 500 or above.
				</para></listitem>
			</itemizedlist>
			</para>
			<example>
			<title>Set <varname>httpcon</varname> parameter</title>
				<programlisting format="linespecific">
...
modparam("http_client", "httpcon", "apione=>http://atlanta.example.com")
modparam("http_client", "httpcon", "apitwo=>http://atlanta.example.com/api/12")
modparam("http_client", "httpcon", "apithree=>http://annabella:mysecret@atlanta.example.com/api/12")
modparam("http_client", "httpcon", "apifour=>http://stockholm.example.com/api/getstuff;timeout=12;failover=apione")
...
				</programlisting>
			</example>
		</section>
		<section id="http_client.p.config_file">
			<title><varname>config_file</varname> (string)</title>
			<para>
			The file name of a configuration file containing definitions
			of http connections. This is an alternative to the
			"httpcon" module parameter - especially when the number of
			options per line gets too big.
			</para>
			<para>
			If the file or directory name starts with a '.' the path will be relative to the
			working directory (<emphasis>at runtime</emphasis>). If it starts
			with a '/' it will be an absolute path and if it starts with anything
			else the path will be relative to the main config file directory
			(e.g.: for kamailio -f /etc/kamailio/kamailio.cfg it will be relative to /etc/kamailio/).
			</para>
			<para>
				The following parameters can be set in the config file, for each connection.
				If a parameter is not specified, the default values set by the modparams will be used.
			</para>
			<itemizedlist>
				<listitem><para>url</para></listitem>
				<listitem><para>username</para></listitem>
				<listitem><para>password</para></listitem>
				<listitem><para>authmethod</para></listitem>
				<listitem><para>keep_connections</para></listitem>
				<listitem><para>useragent</para></listitem>
				<listitem><para>verify_peer</para></listitem>
				<listitem><para>verify_host</para></listitem>
				<listitem><para>client_cert</para></listitem>
				<listitem><para>client_key</para></listitem>
				<listitem><para>cipher_suites</para></listitem>
				<listitem><para>tlsversion - Valid values are:</para>
				<itemizedlist>
				<listitem><para>"DEFAULT"</para></listitem>
				<listitem><para>"TLSv1"</para></listitem>
				<listitem><para>"SSLv22</para></listitem>
				<listitem><para>"SSLv3"</para></listitem>
				<listitem><para>"TLSv1.0"</para></listitem>
				<listitem><para>"TLSv1.1"</para></listitem>
				<listitem><para>"TLSv1.2"</para></listitem>
				</itemizedlist>
				</listitem>
				<listitem><para>timeout</para></listitem>
				<listitem><para>maxdatasize</para></listitem>
				<listitem><para>http_follow_redirect</para></listitem>
				<listitem><para>httpproxy</para></listitem>
				<listitem><para>httpproxyport</para></listitem>
				<listitem><para>failover</para></listitem>
			</itemizedlist>
			See the "httpcon" module parameter for explanation of these settings.
			<para>
			By default no config file is specified.
			</para>
 			<para>
			All the parameters that take filenames as values will be resolved
			using the same rules as for the tls config filename itself: starting
			with a '.' means relative to the working directory, a '/' means an
			absolute path and  anything else a path relative to the directory of
			the current &kamailio; main config file.
			</para>
 			<para>
			To set a string value to null, in order to override default settings,
			you can specify a value of "" - two quotation marks. In order to disable
			a http proxy setting you can set the port to zero.
			</para>
			<example>
			<title>Set <varname>config_file</varname> parameter</title>
				<programlisting format="linespecific">
...
modparam("http_client", "config_file", "httpconnections.cfg)
...
				</programlisting>
			</example>
			<example>
			<title>Short http_client config file</title>
	<programlisting>
[authapiserver]
url = https://api.runbo.example.com/v4.2/auth
timeout = 1
maxdatasize = 4
tlsversion = TLSv1.2
verify_peer = yes
client_key = default_key.pem
client_cert = default_cert.pem
http_follow_redirect = no

	</programlisting>
	</example>

		</section>
		<section id="http_client.p.netinterface">
			<title><varname>netinterface</varname> (string)</title>
			<para>
			Set local network interface to be used for HTTP queries. It
			can be interface name or IP address. For more details see:
			https://curl.haxx.se/libcurl/c/CURLOPT_INTERFACE.html .
			</para>
			<para>
			<emphasis>
				Default value not set.
			</emphasis>
			</para>
			<example>
			<title>Set <varname>netinterface</varname> parameter</title>
				<programlisting format="linespecific">
...
modparam("http_client", "netinterface", "eth0")
...
				</programlisting>
			</example>
		</section>

	</section>

	<section>
	<title>Functions</title>
		<section id="http_client.f.http_connect">
			<title>
				<function moreinfo="none">http_connect(connection, url, [content_type, data,] result)</function>
			</title>
			<para>
			Sends HTTP GET or POST request to a given connection. For a
			POST request, content-type can be specified.
	    	        </para>
			<itemizedlist>
				<listitem>
					<para>
						<emphasis>connection</emphasis> - the name of an existing
						HTTP connection, defined by a httpcon modparam.
					</para>
					<para>
						<emphasis>url</emphasis> - the part of the URL to add to the
						predefined URL in the connection definition.
					</para>
					<para>
						<emphasis>content_type</emphasis> - Used only when posting
						data with HTTP POST. An Internet Media type, like
						"application/json" or "text/plain". Will be added to the
						HTTP request as a header.
					</para>
					<para>
						<emphasis>data</emphasis> - Data or a pseudo variable holding
						data to be posted. (may contain pseudo variable)
					</para>
					<para>
						<emphasis>result</emphasis> - The name of a pseudo variable that
						will have the data of the response from the HTTP server.
					</para>
				</listitem>
			</itemizedlist>
			<para>
			The return value is the HTTP return code (if >=100) or the
			CURL error code if below 100. See the $curlerror pseudovariable
			below for more information about CURL error codes.
	    	        </para>
			<para>
			This function can be used from REQUEST_ROUTE,
			ONREPLY_ROUTE, FAILURE_ROUTE, and BRANCH_ROUTE.
			</para>
			<example>
				<title><function>http_connect()</function> usage</title>
				<programlisting format="linespecific">
...
modparam("http_client", "httpcon", "apiserver=>https://kamailio.org/api/");
...
# POST Request
$var(res) = http_connect("apiserver", "/mailbox", "application/json", "{ ok, {200, ok}}", "$avp(gurka)");
xlog("L_INFO", "API-server HTTP connection: $avp(gurka) Result code $var(res)\n");

$var(res) = http_connect("apiserver", "/callroute", "application/json", "$var(jsondata)", "$avp(route)");
xlog("L_INFO", "API-server HTTP connection: $avp(route) Result code $var(res)\n");
...
				</programlisting>
			</example>
		</section>
		<section id="http_client.f.http_connect_raw">
			<title>
				<function moreinfo="none">http_connect_raw(connection, url, content_type, data, result)</function>
			</title>
			<para>
				Sends HTTP POST request to a given connection.
				Similar to http_connect.
				The only difference is that the data parameter will not be parsed for pseudo variables,
				therefore it can safely be used for content that may contain "$" character like JSON.
			</para>
			<itemizedlist>
				<listitem>
					<para>
						<emphasis>connection</emphasis> - the name of an existing
						HTTP connection, defined by a httpcon modparam.
					</para>
					<para>
						<emphasis>url</emphasis> - the part of the URL to add to the
						predefined URL in the connection definition.
					</para>
					<para>
						<emphasis>content_type</emphasis> - Used only when posting
						data with HTTP POST. An Internet Media type, like
						"application/json" or "text/plain". Will be added to the
						HTTP request as a header.
					</para>
					<para>
						<emphasis>data</emphasis> - Data or a pseudo variable holding
						data to be posted. (will not be parsed for pseudo variable)
					</para>
					<para>
						<emphasis>result</emphasis> - The name of a pseudo variable that
						will have the data of the response from the HTTP server.
					</para>
				</listitem>
			</itemizedlist>
			<para>
			The return value is the HTTP return code (if >=100) or the
			CURL error code if below 100. See the $curlerror pseudovariable
			below for more information about CURL error codes.
	    	        </para>
			<para>
			This function can be used from REQUEST_ROUTE,
			ONREPLY_ROUTE, FAILURE_ROUTE, and BRANCH_ROUTE.
			</para>
			<example>
				<title><function>http_connect_raw()</function> usage</title>
				<programlisting format="linespecific">
...
modparam("http_client", "httpcon", "apiserver=>https://kamailio.org/api/");
...
# POST Request
$var(res) = http_connect_raw("apiserver", "/mailbox", "application/json", "{ ok, {200, ok}}", "$avp(gurka)");
xlog("L_INFO", "API-server HTTP connection: $avp(gurka) Result code $var(res)\n");

$var(res) = http_connect_war("apiserver", "/callroute", "application/json", "$var(jsondata)", "$avp(route)");
xlog("L_INFO", "API-server HTTP connection: $avp(route) Result code $var(res)\n");
...
				</programlisting>
			</example>
		</section>
		<section id="http_client.f.http_get_redirect">
			<title>
				<function moreinfo="none">http_get_redirect(connection, result)</function>
			</title>
			<para>
			When a http connection gets a redirect and the connection is configured to follow
			redirects (301,302) then the target URL, the result of the redirects can be
			retrieved with this function after a successful connection.
	    	        </para>
			<itemizedlist>
				<listitem>
					<para>
						<emphasis>connection</emphasis> - the name of an existing
						HTTP connection, defined by a httpcon modparam.
					</para>
					<para>
						<emphasis>result</emphasis> - The name of a pseudo variable that
						will contain the last used URL.
					</para>
				</listitem>
			</itemizedlist>
			<example>
				<title><function>http_get_redirect()</function> usage</title>
				<programlisting format="linespecific">
...
modparam("http_client", "httpredirect", 1);
...
http_get_redirect("apiserver", "$var(targeturl)");
...
				</programlisting>
			</example>
		</section>
		<section id="http_client.f.http_query">
			<title>
				<function moreinfo="none">http_client_query(url, [post-data], [hdrs], 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>
			Custom headers may be specified via <quote>hdrs</quote> parameter
			(e.g., Content-Type).
			</para>
			<para>
			Either of <quote>post-data</quote> or <quote>hdrs</quote> can be
			also set to empty string in order to be ignored.
			</para>
			<para>
			If HTTP server returns a class 2xx, 3xx or 4xx reply,
			the first line or the entire reply body (if any) is
			stored in <quote>result</quote> parameter,
			which must be a	writable pseudo	variable. See the query_result
			parameter for controlling what value to be stored in the result
			variable.
			</para>
			<para>
			Function returns reply code of HTTP reply or -1
			if something went wrong.
			</para>
			<para>
			This function can be used from ANY_ROUTE.
			</para>
			<para>
			Note that this function is based on the http_query function in the utils module.
			It is changed to use the same base library and settings as the rest of the functions in this module.
			</para>
			<example>
				<title><function>http_client_query()</function> usage</title>
				<programlisting format="linespecific">
...
# GET-Request
http_client_query("http://api.com/index.php?r_uri=$(ru{s.escape.param})&amp;f_uri=$(fu{s.escape.param})",
	   "$var(result)");
switch ($rc) {
    ...
}
...
# POST-Request
http_client_query("http://api.com/index.php",
    "r_uri=$(ru{s.escape.param})&amp;f_uri=$(fu{s.escape.param})",
    "$var(result)");
}
...
# POST-Request
http_client_query("http://api.com/index.php", "src=$si",
    "Content-Type: text/plain", "$var(result)");
...
				</programlisting>
			</example>
		</section>
		<section id="http_client.f.http_get">
			<title>
				<function moreinfo="none">http_client_get(url, body, hdrs, respv)</function>
			</title>
			<para>
				Perform a HTTP GET request to "url", storing the response body
				in the "respv" variable. The "body" and "hdrs" can be empty strings
				to skip setting them. The first three parameters can contain
				variables that are evaluated at runtime. The "respv" has to be
				the name of a writable variable.
			</para>
			<para>
				Note: usually HTTP GET requests should have no body, according to
				specs the body in HTTP GET does not affect the response, but is
				not explicitely forbidden.
			</para>
			<example>
				<title><function>http_client_get()</function> usage</title>
				<programlisting format="linespecific">
...
http_client_get("http://api.com/index.php?r_uri=$(ru{s.escape.param})&amp;f_uri=$(fu{s.escape.param})",
	   "", "X-Token: abc", "$var(result)");
switch ($rc) {
    ...
}
...
				</programlisting>
			</example>
		</section>
	</section>
	<section>
	<title>Pseudovariables</title>
		<section >
			<title>
				<function moreinfo="none">$curlerror(error)</function>
			</title>
			<para>
			The cURL library returns error codes from the protocol used. If an error
			happens, a cURL specific error code below 100 is returned.
			The $curlerror pv returns a text string representing the error.
			For more information on cURL error codes, please visit
			http://curl.haxx.se/libcurl/c/libcurl-errors.html
			</para>
		</section>
	</section>
	<section>
	<title>RPC Commands</title>
		<section id="httpclient.r.httpclient.listcon">
			<title><function moreinfo="none">httpclient.listcon</function></title>
			<para>
				Lists all defined httpcon connections
			</para>
		<para>Parameters:</para>
		<itemizedlist>
			<listitem><para>No parameters</para></listitem>
		</itemizedlist>
		</section>
	</section>
	<section>
	<title>Counters</title>
		<section >
			<title>
				<function moreinfo="none">httpclient.connections</function>
			</title>
			<para>
				The number of connection definitions that are in-memory.
			</para>
		</section>
		<section >
			<title>
				<function moreinfo="none">httpclient.connok</function>
			</title>
			<para>
				The number of successful connections since &kamailio; start
			</para>
		</section>
		<section >
			<title>
				<function moreinfo="none">httpclient.connfail</function>
			</title>
			<para>
				The number of failed connections since &kamailio; start
			</para>
		</section>
	</section>

	<section id="http_client.s.remarks">
		<title>Remarks</title>
		<para>
			Note: libcurl leak in CentOS 6 - this module uses libcurl library
			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>
	</section>
</chapter>
