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

<chapter>
    <chapterinfo>
	<revhistory>
	    <revision>
		<revnumber>$Revision: 1.1 $</revnumber>
		<date>$Date: 2003/07/14 21:03:05 $</date>
	    </revision>
	</revhistory>
    </chapterinfo>
    <title>User's Guide</title>
    
    <section>
	<title>Overview</title>
	<para>
	    Enum module implements enum_query function that makes an enum query based on the user
	    part of the current request <acronym>URI</acronym>. 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 name, <function moreinfo="none">enum_query</function>enum_query
	    queries from <abbrev>DNS</abbrev> its <abbrev>NAPTR</abbrev> records. From the possible
	    response the current version of enum_query chooses the <emphasis>FIRST</emphasis>
	    record, whose flags field has string value <quote>u</quote> and whose services field has
	    string value <quote>e2u+[service:]sip</quote> (case is ignored in both cases).
	    <quote>service</quote> is given to <function moreinfo="none">enum_query</function> as a
	    parameter. If its value is <quote></quote>, then <quote>e2u+sip</quote> is looked for.
	    If no such record is found, <function moreinfo="none">enum_query</function> returns -1.
	</para>
	<para>
	    If such a record is found, <function moreinfo="none">enum_query</function> checks if its 
	    regexp field is of the form !pattern!replacement!. If yes, 
	    <function moreinfo="none">enum_query</function> replaces the current
	    Request-URI with replacement, which it assumes to contain a <abbrev>SIP</abbrev> or 
	    <abbrev>SIPS</abbrev> type <abbrev>URI</abbrev>, and returns value 1.
	</para>
	<para>
	    If the regexp field is not of the form !pattern!replacement!, 
	    <function moreinfo="none">enum_query</function> returns -1.
	</para>
	<para>
	    In addition to <function moreinfo="none">enum_query</function>, enum module implements
	    <function moreinfo="none">is_from_user_e164</function> function that checks if the user
	    part of from <abbrev>URI</abbrev> is an <abbrev>E164</abbrev> number.
	</para>
	<para>
	    TODO: In <function moreinfo="none">enum_query</function>, proper implementation of the
	    <abbrev>NAPTR</abbrev> record selection algorithm could be implemented by taking into
	    account the order and preference fields (see draft-ietf-sipping-e164-02).
	</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. 
	    </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>
    <section>
	<title>Exported Functions</title>
	<section>
	    <title><function moreinfo="none">enum_query(service)</function></title>
	    <para>
		Replaces the current Request-URI with the result of a successful enum query on the
		user part of the current Request-URI, which is assumed to be of the form
		+up-to-15-decimal-digits.  An <abbrev>NAPTR</abbrev> record whose flags field has
		string value <quote>u</quote> and whose services field has string value
		<quote>e2u+service:sip</quote> or <quote>e2u+sip</quote> (if service string ==
		<quote></quote>) is looked for.
		Returns -1 if <function moreinfo="none">enum_query</function> fails and 1 otherwise.
	    </para>
	    <para>Meaning of the parameters is as follows:</para>
	    <itemizedlist>
		<listitem>
		    <para><emphasis>service</emphasis> - service string to be used in the service
		    field.
		    </para>
		</listitem>
	    </itemizedlist>
	    <example>
		<title><function moreinfo="none">enum_query</function> usage</title>
		<programlisting format="linespecific">
...
enum_query("");
...
</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>
	    <example>
		<title><function moreinfo="none">is_from_user_e164</function> usage</title>
		<programlisting format="linespecific">
...
if (is_from_user_e164()) {
    ....
};
...
</programlisting>
	    </example>
	</section>
    </section>
</chapter>

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