<?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 an embedded HTTP/2 server using nghttpd2 library.
	</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>none</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>libnghttp2</emphasis> - libnghttpd library (v1.43.0+)
			</para>
			</listitem>
			</itemizedlist>
		</para>
	</section>
	</section>

	<section>
	<title>Parameters</title>
	<section id="nghttp2.p.listen_addr">
		<title><varname>listen_addr</varname> (str)</title>
		<para>
			IPv4 address to listen for HTTP2 connection. If not set, then it
			listens on all local addresses (port has to be specified by
			listen_port parameter).
		</para>
		<para>
		<emphasis>
			Default value is "" (empty - not set).
		</emphasis>
		</para>
		<example>
		<title>Set <varname>listen_addr</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("nghttp2", "listen_addr", "127.0.0.1")
...
</programlisting>
		</example>
	</section>
	<section id="nghttp2.p.listen_port">
		<title><varname>listen_port</varname> (str)</title>
		<para>
			Port or service name to listen for HTTP2 connection.
		</para>
		<para>
		<emphasis>
			Default value is "8282".
		</emphasis>
		</para>
		<example>
		<title>Set <varname>listen_port</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("nghttp2", "listen_port", "8284")
...
</programlisting>
		</example>
	</section>
	<section id="nghttp2.p.event_callback">
		<title><varname>event_callback</varname> (str)</title>
		<para>
			The name of the function in the kemi configuration file (embedded
			scripting language such as Lua, Python, ...) to be executed instead
			of event_route[nghttp2:request] block.
		</para>
		<para>
			The function has one string parameter with the value "nghttp2:request".
		</para>
		<para>
		<emphasis>
			Default value is 'empty' (no function is executed for events).
		</emphasis>
		</para>
		<example>
		<title>Set <varname>event_callback</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("nghttp2", "event_callback", "ksr_nghttp2_event")
...
-- event callback function implemented in Lua
function ksr_nghttp2_event(evname)
	KSR.info("===== nghttp2 module triggered event: " .. evname .. "\n");
	return 1;
end
...
</programlisting>
	    </example>
	</section>
	</section>

	<section>
	<title>Functions</title>
	<section id="nghttp2.f.nghttp2_reply">
	    <title>
		<function moreinfo="none">nghttp2_reply(code, body)</function>
	    </title>
	    <para>
		Send back a reply with body. The body can be empty string. Both parameters
		can contain variables.
	    </para>
		<example>
		<title><function>nghttp2_reply</function> usage</title>
		<programlisting format="linespecific">
...
event_route[nghttp2:request] {
    nghttp2_reply("200",
        "&lt;html&gt;&lt;body&gt;OK&lt;/body&gt;&lt;/html&gt;");
}
...
</programlisting>
	    </example>
	</section>
	<section id="nghttp2.f.nghttp2_reply_header">
	    <title>
		<function moreinfo="none">nghttp2_reply_header(name, value)</function>
	    </title>
	    <para>
		Set a header to be added to reply. There can be up to 15 headers.
	    </para>
		<example>
		<title><function>nghttp2_reply</function> usage</title>
		<programlisting format="linespecific">
...
event_route[nghttp2:request] {
    nghttp2_reply_header("Content-Type", "text/html");
    nghttp2_reply_header("My-Header", "xyz");
    nghttp2_reply("200",
        "&lt;html&gt;&lt;body&gt;OK&lt;/body&gt;&lt;/html&gt;");
}
...
</programlisting>
	    </example>
	</section>
	</section>

   <section>
    <title>Event Routes</title>
    <section id="nghttp2.evr.request">
        <title>
        <function moreinfo="none">nghttp2:request</function>
        </title>
        <para>
			The event route is executed when a new HTTP request is received.
        </para>
        <para>
			Inside it, the $nghttp2(...) group of variables is available, giving
			access to several attributes of the HTTP request, such as method,
			URL path, data (body) or headers.
        </para>
        <programlisting  format="linespecific">
...
...
loadmodule "nghttp2.so
...
event_route[nghttp2:request] {
    xinfo("request: $nghttp2(method) - url: $nghttp2(path) - data: [$nghttp2(data)]\n");
    nghttp2_reply("200", "OK", "text/html",
        "&lt;html&gt;&lt;body&gt;OK&lt;/body&gt;&lt;/html&gt;");
}
...
        </programlisting>
	</section>
	</section>

</chapter>
