<!-- Enum Module User's Guide -->

<chapter>
	<chapterinfo>
	<revhistory>
		<revision>
		<revnumber>$Revision: 1.5 $</revnumber>
		<date>$Date: 2006/01/30 16:40:14 $</date>
		</revision>
	</revhistory>
	</chapterinfo>
	<title>User's Guide</title>

	<section id="sec-overview">
	<title>Overview</title>
	<para>
		Enum module implements enum_query function that makes an enum query 
		based on the user part of the current Request-URI. The function 
		assumes that the user part consists of an international phone number 
		of the form +decimal-digits, where the number of digits is at
		least 2 and at most 15. Out of this number 
		<function moreinfo="none">enum_query</function> forms a domain name, 
		where the digits are in reverse order and separated by dots followed by 
		domain suffix that by default is <quote>e164.arpa.</quote>. For example, 
		if the user part is +35831234567, the domain
		name will be <quote>7.6.5.4.3.2.1.3.8.5.3.e164.arpa.</quote>.
	</para>
	<para>
		After forming the domain name, 
		<function moreinfo="none">enum_query</function> queries
		DNS for its NAPTR records. From the possible response 
		<function moreinfo="none">enum_query</function> chooses those records, 
		whose flags field has string value "u", and whose services field has 
		string value "e2u+[service:]sip" or 
		"e2u+type[:subtype][+type[:subtype]...]" (case is ignored in both 
		cases), and whose regexp field is of the form !pattern!replacement!.
	</para>
	<para>
		Then <function moreinfo="none">enum_query</function> sorts the chosen 
		NAPTR records based on their &lt;order, preference&gt;.  After sorting, 
		<function moreinfo="none">enum_query</function> replaces the current 
		Request URI by applying regexp of the most preferred NAPTR record its 
		user part and appends to the request new branches by applying regexp of 
		each remaining NAPTR record to the user part of the
		current Request URI. If a new URI is a tel URI, 
		<function moreinfo="none">enum_query</function> appends to it as tel 
		URI parameters the value of tel_uri_params module parameter. Finally, 
		<function moreinfo="none">enum_query</function> associates a q value 
		with each new URI based on the &lt;order, preference&gt; of the 
		corresponding NAPTR record.
	</para>
	<para>
		When using <function moreinfo="none">enum_query</function> without any 
		parameters, it searches for NAPTRs with service type "e2u+sip" in the 
		default enum tree. When using 
		<function moreinfo="none">enum_query</function> with a single parameter, 
		this parameter will be used as enum tree. When using 
		<function moreinfo="none">enum_query</function> 
		with two parameters, the functionality depends on the first letter in 
		the second parameter. When the first letter is not a '+' sign, the 
		second parameter will be used to search for NAPTRs with service type 
		"e2u+parameter:sip". When the second parameter starts with a '+' sign, 
		the ENUM lookup also supports compound NAPTRs 
		(e.g. "e2u+voice:sip+video:sip") and searching for multiple service 
		types within one lookup. Multiple service types must be separeted 
		by a '+' sign.
	</para>
	<para>
		Most of the time you want to route based on the RURI.  On rare occasions
		you may wish to route based on the user part of the <quote>From:</quote> tag,
		analogous to source based policy routing in the ip world. The function
		<function moreinfo="none">enum_fquery</function> mimics the behaviour
		of the <function moreinfo="none">enum_query</function> function except the
		user part of the <quote>From:</quote> is used for the enum lookup instead of the user
		part of the RURI.  Obviously the user part of the RURI is still used in the
		naptr regexp.
	</para>
	<para>
		Enum query returns 1 if the current Request URI was replaced 
		and -1 if not.
	</para>
	<para>
		Enum module also implements is_from_user_e164 function that checks if 
		the user part of from URI is an E164 number.
	</para>
	<para>
		Enum module also implements is_from_user_enum function.
		This function does an enum lookup on the from user and
		returns true if found, false otherwise.
	</para>
	</section>

	<section>
	<title>Dependencies</title>
	<para>
		The module depends on the following modules (in the other words the 
		listed modules must be loaded before this module):
		<itemizedlist>
		<listitem>
			<para>No dependencies.</para>
		</listitem>
		</itemizedlist>
	</para>
	</section>

	<section>
	<title>Exported Parameters</title>
	<section>
		<title><varname>domain_suffix</varname> (string)</title>
		<para>
		The domain suffix to be added to the domain name obtained from
		the digits of an <acronym>E164</acronym> number. Can be overridden 
		by a parameter to enum_query.
		</para>
		<para>
		Default value is <quote>e164.arpa.</quote>
		</para>
		<example>
		<title>Setting domain_suffix module parameter</title>
		<programlisting format="linespecific">
modparam("enum", "domain_suffix", "e1234.arpa.")
</programlisting>
		</example>
	</section>

	<section>
		<title><varname>tel_uri_params</varname> (string)</title>
		<para>
		A string whose contents is appended to each new tel URI in the 
		request as tel URI parameters.
		</para>
		<note>
		<para>
			Currently &ser; does not support tel URIs. This means that at present
			tel_uri_params is appended as URI parameters to every URI.
		</para>
		</note>
		<para>
		Default value is <quote></quote>
		</para>
		<example>
		<title>Setting tel_uri_params module parameter</title>
		<programlisting format="linespecific">
modparam("enum", "tel_uri_params", ";npdi")
</programlisting>
		</example>
	</section>
	</section>

	<section>
	<title>Exported Functions</title>
	<section>
		<title>
		<function moreinfo="none">enum_query(),enum_query("suffix"), enum_query("suffix", "service")</function>
		</title>
		<para>
		The function performs an enum query and rewrites the Request-URI with 
		the result of the query. See <xref linkend="sec-overview"/> for more 
		information.
		</para>
		<para>Meaning of the parameters is as follows:</para>
		<itemizedlist>
		<listitem>
			<para><emphasis>suffix</emphasis> - Suffix to be appended to the 
			domain name.
			</para>
		</listitem>
		<listitem>
			<para><emphasis>service</emphasis> - Service string to be used in 
			the service field.
			</para>
		</listitem>
		</itemizedlist>
		<para>
		This function can be used from REQUEST_ROUTE.
		</para>
		<example>
		<title><function moreinfo="none">enum_query</function> usage</title>
		<programlisting format="linespecific">
...
# search for "e2u+sip" in freenum.org 
enum_query("freenum.org.");
...
# search for "e2u+sip" in default tree (configured as parameter)
enum_query();
...
# search for "e2u+voice:sip" in e164.arpa
enum_query("e164.arpa.","voice");
...
# search for service type "sip" or "voice:sip" or "video:sip"
# note the '+' sign in front of the second parameter
enum_query("e164.arpa.","+sip+voice:sip+video:sip");
...
# quering for service sip and voice:sip
enum_query("e164.arpa.");
enum_query("e164.arpa.","voice");
# or use instead
enum_query("e164.arpa.","+sip+voice:sip");
...
</programlisting>
		</example>
	</section>

	<section>
		<title>
		<function moreinfo="none">enum_fquery(),enum_fquery("suffix"), enum_fquery("suffix", "service")</function>
		</title>
		<para>
		The function performs an enum query
		on the user part of the From: tag and rewrites the Request-URI with 
		the result of the query. See <xref linkend="sec-overview"/> for more 
		information.
		</para>
		<para>Meaning of the parameters is as follows:</para>
		<itemizedlist>
		<listitem>
			<para><emphasis>suffix</emphasis> - Suffix to be appended to the 
			domain name.
			</para>
		</listitem>
		<listitem>
			<para><emphasis>service</emphasis> - Service string to be used in 
			the service field.
			</para>
		</listitem>
		</itemizedlist>
		<para>
		This function can be used from REQUEST_ROUTE.
		</para>
		<example>
		<title><function moreinfo="none">enum_fquery</function> usage</title>
		<programlisting format="linespecific">
...
# search for "e2u+sip" in freenum.org 
enum_fquery("freenum.org.");
...
# search for "e2u+sip" in default tree (configured as parameter)
enum_fquery();
...
# search for "e2u+voice:sip" in e164.arpa
enum_fquery("e164.arpa.","voice");
...
# search for service type "sip" or "voice:sip" or "video:sip"
# note the '+' sign in front of the second parameter
enum_fquery("e164.arpa.","+sip+voice:sip+video:sip");
...
# quering for service sip and voice:sip
enum_fquery("e164.arpa.");
enum_fquery("e164.arpa.","voice");
# or use instead
enum_fquery("e164.arpa.","+sip+voice:sip");
...
</programlisting>
		</example>
	</section>

	<section>
		<title><function moreinfo="none">is_from_user_e164()</function></title>
		<para>
		Checks if the user part of from <abbrev>URI</abbrev> an 
		<abbrev>E164</abbrev> number of the form +[0-9]{2,15}. Returns 1 if 
		yes and -1 if not.
		</para>
		<para>
		This function can be used from REQUEST_ROUTE.
		</para>
		<example>
		<title><function moreinfo="none">is_from_user_e164</function> usage</title>
		<programlisting format="linespecific">
...
if (is_from_user_e164()) {
	....
};
...
</programlisting>
		</example>
	</section>

	<section>
		<title><function moreinfo="none">is_from_user_enum()</function></title>
		<para>
		Checks if the user part of from <abbrev>URI</abbrev>
		is found in an enum lookup.
		Returns 1 if yes and -1 if not.
		</para>
		<para>
		This function can be used from REQUEST_ROUTE.
		</para>
		<example>
		<title><function moreinfo="none">is_from_user_enum</function> usage</title>
		<programlisting format="linespecific">
...
if (is_from_user_enum()) {
	....
};
...
</programlisting>
		</example>
	</section>
	</section>
</chapter>

<!-- Keep this element at the end of the file
Local Variables:
sgml-parent-document: ("enum.sgml" "Book" "chapter")
End:
-->