src/modules/phonenum/doc/phonenum_admin.xml
12b2a249
 <?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>
4d2e1172
 	<section id="phonenum.p.smode">
12b2a249
 	    <title><varname>smode</varname> (int)</title>
 	    <para>
 		Phone number search mode.
 	    </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>
 
     <section>
 	<title>Functions</title>
4d2e1172
 	<section id="phonenum.f.phonenum_match">
12b2a249
 	    <title>
 		<function moreinfo="none">phonenum_match(num, pvc)</function>
 	    </title>
 	    <para>
 			Match num against the libphonenumber and set the attributes inside
 			the pvc 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">
 ...
70a61e0b
 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");
     }
 }
12b2a249
 ...
 </programlisting>
 	    </example>
 	</section>
4d2e1172
 	<section id="phonenum.f.phonenum_match_cn">
 	    <title>
77316f75
 		<function moreinfo="none">phonenum_match_cn(num, cnc, pvc)</function>
4d2e1172
 	    </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>
12b2a249
     </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>
70a61e0b
 					<emphasis>number</emphasis> - phone number that is matched
12b2a249
 				</para></listitem>
 				<listitem><para>
70a61e0b
 					<emphasis>valid</emphasis> - 1 if the matched number has a
 					valid result; 0 otherwise
12b2a249
 				</para></listitem>
 				<listitem><para>
70a61e0b
 					<emphasis>normalized</emphasis> - normalized phone number
12b2a249
 				</para></listitem>
 				<listitem><para>
70a61e0b
 					<emphasis>cctel</emphasis> - country code for phone number
 				</para></listitem>
 				<listitem><para>
a6c5ec17
 					<emphasis>ccname</emphasis> - country code name
 				</para></listitem>
 				<listitem><para>
70a61e0b
 					<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.
12b2a249
 				</para></listitem>
 			</itemizedlist>
 			</listitem>
 		</itemizedlist>
 		<para>
 		Exported pseudo-variables are documented at &kamwikilink;.
 		</para>
 	</section>
 
 </chapter>