<?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 allows real-time queries against the libphonenumber
		to be performed from the config script. With that it is possible
		to get normalize and get details about a phone number.
	</para>
	<para>
		More details about libphonenumber can be found at
		<ulink url="https://github.com/googlei18n/libphonenumber">
			https://github.com/googlei18n/libphonenumber</ulink>.
	</para>
	<para>
		This module exports a new class of pseudo-variables -
		$phn(pvc=&gt;key) - to enable access to the results of a query to the
		database.
	</para>
	<para>
		Many queries can be done and store results in different containers to
		be able to use in parallel.
	</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>libphonenumber</emphasis> - the phone number library.
			</para>
		    </listitem>
	    	</itemizedlist>
	    </para>
	</section>
    </section>
    <section>
	<title>Parameters</title>
	<section id="phonenum.p.smode">
	    <title><varname>smode</varname> (int)</title>
	    <para>
		Phone number search mode (not in use yet).
	    </para>
	    <para>
		<emphasis>
		    Default value is <quote>0</quote>.
		</emphasis>
	    </para>
	    <example>
		<title>Set <varname>smode</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("phonenum", "smode", 0)
...
</programlisting>
	    </example>
	</section>
	<section id="phonenum.p.resid">
	    <title><varname>resid</varname> (str)</title>
	    <para>
		Preregister result container id during initialization, enabling the use
		of the module in KEMI scripts. In native &kamailio;.cfg file, registration
		is done when parsing config and finding variables.
	    </para>
	    <para>
		<emphasis>
		    Default value is <quote></quote> (empty).
		</emphasis>
	    </para>
	    <example>
		<title>Set <varname>resid</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("phonenum", "resid", "src")
...
if(phonenum_match("1-484-555-8888", "src")) {
   ...
}
...
</programlisting>
	    </example>
	</section>
	</section>

    <section>
	<title>Functions</title>
	<section id="phonenum.f.phonenum_match">
	    <title>
		<function moreinfo="none">phonenum_match(num, pvc)</function>
	    </title>
	    <para>
			Match num against the libphonenumber and set the attributes inside
			the pvc result container. The function has to be called before accessing
			a key via: $phn(pvc=&gt;key).
	    </para>
	    <para>
	    	The parameters can be static strings or strings with variables.
	    </para>
	    <para>
	    	It can be used from ANY_ROUTE.
	    </para>
		<example>
		<title><function>phonenum_match</function> usage</title>
		<programlisting format="linespecific">
...
if(phonenum_match("1-484-555-8888", "src")) {
    if($phn(src=&gt;valid)==1) {
        xlog("number normalized to: $phn(src=&gt;normalized)\n");
    } else {
        xlog("number normalization error: $phn(src=&gt;error)\n");
    }
}
...
</programlisting>
	    </example>
	</section>
	<section id="phonenum.f.phonenum_match_cn">
	    <title>
		<function moreinfo="none">phonenum_match_cn(num, cnc, pvc)</function>
	    </title>
	    <para>
			Match num against the libphonenumber and set the attributes inside
			the pvc container, restricting the rules with a country name code
			(two letter, e.g: "DE", "US", "ES"). The function has to be called
			before accessing a key via: $phn(pvc=&gt;key).
	    </para>
	    <para>
			The parameters can be static strings or strings with variables.
	    </para>
	    <para>
			It can be used from ANY_ROUTE.
	    </para>
		<example>
		<title><function>phonenum_match_cn</function> usage</title>
		<programlisting format="linespecific">
...
if(phonenum_match_cn("1-484-555-8888", "US", "src")) {
    if($phn(src=&gt;valid)==1) {
        xlog("number normalized to: $phn(src=&gt;normalized)\n");
    } else {
        xlog("number normalization error: $phn(src=&gt;error)\n");
    }
}
...
</programlisting>
	    </example>
	</section>
    </section>

	<section>
		<title>Pseudo Variables</title>
		<itemizedlist>
			<listitem><para>
				<emphasis>$phn(pvc=&gt;key)</emphasis> - <emphasis>pvc</emphasis>
				is an identifier for this query result; it is designated by
				the second parameter of phonenum_match().
				The <emphasis>key</emphasis> can be one of the following:
				</para>
			<itemizedlist>
				<listitem><para>
					<emphasis>number</emphasis> - phone number that is matched
				</para></listitem>
				<listitem><para>
					<emphasis>valid</emphasis> - 1 if the matched number has a
					valid result; 0 otherwise
				</para></listitem>
				<listitem><para>
					<emphasis>normalized</emphasis> - normalized phone number
				</para></listitem>
				<listitem><para>
					<emphasis>cctel</emphasis> - country code for phone number
				</para></listitem>
				<listitem><para>
					<emphasis>ccname</emphasis> - country code name
				</para></listitem>
				<listitem><para>
					<emphasis>ltype</emphasis> - local network type
				</para></listitem>
				<listitem><para>
					<emphasis>ndesc</emphasis> - phone number description
				</para></listitem>
				<listitem><para>
					<emphasis>error</emphasis> - error string if phone number
					matching fails.
				</para></listitem>
			</itemizedlist>
			</listitem>
		</itemizedlist>
		<para>
		Exported pseudo-variables are documented at &kamwikilink;.
		</para>
	</section>

</chapter>

