michael@12: <!-- Enum Module User's Guide -->
michael@12: 
michael@12: <chapter>
michael@12: 	
michael@12: 	<title>&adminguide;</title>
michael@12: 
michael@12: 	<section id="sec-overview">
michael@12: 	<title>Overview</title>
michael@12: 	<para>
michael@12: 		Enum module implements [i_]enum_query functions that make an enum query 
michael@12: 		based on the user part of the current Request-URI. These functions
michael@12: 		assume that the user part consists of an international phone number 
michael@12: 		of the form +decimal-digits, where the number of digits is at
michael@12: 		least 2 and at most 15. Out of this number 
michael@12: 		<function moreinfo="none">enum_query</function> forms a domain name, 
michael@12: 		where the digits are in reverse order and separated by dots followed by 
michael@12: 		domain suffix that by default is <quote>e164.arpa.</quote>. For example, 
michael@12: 		if the user part is +35831234567, the domain
michael@12: 		name will be <quote>7.6.5.4.3.2.1.3.8.5.3.e164.arpa.</quote>.
michael@12: 		<function moreinfo="none">i_enum_query</function> operates in a similar
michael@12: 		fashion. The only difference is that it adds a label (default "i")
michael@12: 		to branch off from the default, user-ENUM tree to an infrastructure ENUM tree.
michael@12: 	</para>
michael@12: 	<para>
michael@12: 		After forming the domain name, 
michael@12: 		<function moreinfo="none">enum_query</function> queries
michael@12: 		DNS for its NAPTR records. From the possible response 
michael@12: 		<function moreinfo="none">enum_query</function> chooses those records, 
michael@12: 		whose flags field has string value "u", and whose services field has 
michael@12: 		string value "e2u+[service:]sip" or 
michael@12: 		"e2u+type[:subtype][+type[:subtype]...]" (case is ignored in both 
michael@12: 		cases), and whose regexp field is of the form !pattern!replacement!.
michael@12: 	</para>
michael@12: 	<para>
michael@12: 		Then <function moreinfo="none">enum_query</function> sorts the chosen 
michael@12: 		NAPTR records based on their &lt;order, preference&gt;.  After sorting, 
michael@12: 		<function moreinfo="none">enum_query</function> replaces the current 
michael@12: 		Request URI by applying regexp of the most preferred NAPTR record its 
michael@12: 		user part and appends to the request new branches by applying regexp of 
michael@12: 		each remaining NAPTR record to the user part of the
michael@12: 		current Request URI. If a new URI is a tel URI, 
michael@12: 		<function moreinfo="none">enum_query</function> appends to it as tel 
michael@12: 		URI parameters the value of tel_uri_params module parameter. Finally, 
michael@12: 		<function moreinfo="none">enum_query</function> associates a q value 
michael@12: 		with each new URI based on the &lt;order, preference&gt; of the 
michael@12: 		corresponding NAPTR record.
michael@12: 	</para>
michael@12: 	<para>
michael@12: 		When using <function moreinfo="none">enum_query</function> without any 
michael@12: 		parameters, it searches for NAPTRs with service type "e2u+sip" in the 
michael@12: 		default enum tree. When using 
michael@12: 		<function moreinfo="none">enum_query</function> with a single parameter, 
michael@12: 		this parameter will be used as enum tree. When using 
michael@12: 		<function moreinfo="none">enum_query</function> 
michael@12: 		with two parameters, the functionality depends on the first letter in 
michael@12: 		the second parameter. When the first letter is not a '+' sign, the 
michael@12: 		second parameter will be used to search for NAPTRs with service type 
michael@12: 		"e2u+parameter:sip". When the second parameter starts with a '+' sign, 
michael@12: 		the ENUM lookup also supports compound NAPTRs 
michael@12: 		(e.g. "e2u+voice:sip+video:sip") and searching for multiple service 
michael@12: 		types within one lookup. Multiple service types must be separeted 
michael@12: 		by a '+' sign.
michael@12: 	</para>
michael@12: 	<para>
michael@12: 		Most of the time you want to route based on the RURI.  On rare occasions
michael@12: 		you may wish to route based on something else. The function
michael@12: 		<function moreinfo="none">enum_pv_query</function> mimics the behavior
michael@12: 		of the <function moreinfo="none">enum_query</function> function except the
michael@12: 		E.164 number in its pseudo variable argument is used for the enum lookup instead of the user
michael@12: 		part of the RURI.  Obviously the user part of the RURI is still used in the
michael@12: 		NAPTR regexp.
michael@12: 	</para>
michael@12: 	<para>
michael@12: 		Enum query returns 1 if the current Request URI was replaced 
michael@12: 		and -1 if not.
michael@12: 	</para>
michael@12: 	<para>
michael@13: 		In addition to standard ENUM, support for ISN (ITAD Subscriber
michael@13: 		Numbers) is provided as well. To allow ISN lookups to resolve,
michael@13: 		a different formatting algorithm is expected by the DNS server.
michael@13: 		Whereas a ENUM NAPTR record expects a DNS query of the form
michael@13: 		9.8.7.6.5.4.3.2.1.<suffix>, ISN method expects a DNS query of
michael@13: 		the form 6.5.1212.<suffix>. That is, a valid ISN number includes
michael@13: 		a prefix of '56' in the example. The rest of the number is a
michael@13: 		ITAD (Internet Telephony Administrative Domain) as defined
michael@13: 		in RFCs 3872 and 2871, and as allocated by the IANA in
michael@13: 		http://www.iana.org/assignments/trip-parameters. The ITAD is
michael@13: 		left intact and not refersed as ENUM requires. To learn more
michael@13: 		about ISN please refer to documents at www.freenum.org.
michael@13: 	</para>
michael@13: 	<para>
michael@13: 		To complete a ISN lookup on the user part of the Request-URI,
michael@13: 		isn_query() is used instead of enum_query().
michael@13: 	</para>
michael@13: 	<para>
michael@12: 		Enum module also implements is_from_user_enum function.
michael@12: 		This function does an enum lookup on the from user and
michael@12: 		returns true if found, false otherwise.
michael@12: 	</para>
michael@12: 	</section>
michael@12: 
michael@12: 	<section>
michael@12: 	<title>Dependencies</title>
michael@12: 	<para>
michael@12: 		The module depends on the following modules (in the other words the 
michael@12: 		listed modules must be loaded before this module):
michael@12: 		<itemizedlist>
michael@12: 		<listitem>
michael@12: 			<para>No dependencies.</para>
michael@12: 		</listitem>
michael@12: 		</itemizedlist>
michael@12: 	</para>
michael@12: 	</section>
michael@12: 
michael@12: 	<section>
michael@12: 	<title>Exported Parameters</title>
michael@12: 	<section>
michael@12: 		<title><varname>domain_suffix</varname> (string)</title>
michael@12: 		<para>
michael@12: 		The domain suffix to be added to the domain name obtained from
michael@12: 		the digits of an <acronym>E164</acronym> number. Can be overridden 
michael@12: 		by a parameter to enum_query.
michael@12: 		</para>
michael@12: 		<para>
michael@12: 		Default value is <quote>e164.arpa.</quote>
michael@12: 		</para>
michael@12: 		<example>
michael@12: 		<title>Setting domain_suffix module parameter</title>
michael@12: 		<programlisting format="linespecific">
michael@12: modparam("enum", "domain_suffix", "e1234.arpa.")
michael@12: </programlisting>
michael@12: 		</example>
michael@12: 	</section>
michael@12: 
michael@12: 	<section>
michael@12: 		<title><varname>tel_uri_params</varname> (string)</title>
michael@12: 		<para>
michael@12: 		A string whose contents is appended to each new tel URI in the 
michael@12: 		request as tel URI parameters.
michael@12: 		</para>
michael@12: 		<note>
michael@12: 		<para>
michael@12: 			Currently &osips; does not support tel URIs. This means that at present
michael@12: 			tel_uri_params is appended as URI parameters to every URI.
michael@12: 		</para>
michael@12: 		</note>
michael@12: 		<para>
michael@12: 		Default value is <quote></quote>
michael@12: 		</para>
michael@12: 		<example>
michael@12: 		<title>Setting tel_uri_params module parameter</title>
michael@12: 		<programlisting format="linespecific">
michael@12: modparam("enum", "tel_uri_params", ";npdi")
michael@12: </programlisting>
michael@12: 		</example>
michael@12: 	</section>
michael@12:         <section>
michael@12:                 <title><varname>i_enum_suffix</varname> (string)</title>
michael@12:                 <para>
michael@12:                 The domain suffix to be used for i_enum_query() lookups.
michael@12:                 Can be overridden by a parameter to i_enum_query.
michael@12:                 </para>
michael@12:                 <para>
michael@12:                 Default value is <quote>e164.arpa.</quote>
michael@12:                 </para>
michael@12:                 <example>
michael@12:                 <title>Setting i_enum_suffix module parameter</title>
michael@12:                 <programlisting format="linespecific">
michael@12: modparam("enum", "i_enum_suffix", "e1234.arpa.")
michael@12: </programlisting>
michael@12:                 </example>
michael@12:         </section>
michael@12:         <section>
michael@13:                 <title><varname>isn_suffix</varname> (string)</title>
michael@13:                 <para>
michael@13:                 The domain suffix to be used for isn_query() lookups. Can
michael@13:                 be overridden by a parameter to isn_query.
michael@13:                 </para>
michael@13:                 <para>
michael@13:                 Default value is <quote>freenum.org.</quote>
michael@13:                 </para>
michael@13:                 <example>
michael@13:                 <title>Setting isn_suffix module parameter</title>
michael@13:                 <programlisting format="linespecific">
michael@13: modparam("enum", "isn_suffix", "freenum.org.")
michael@13: </programlisting>
michael@13:                 </example>
michael@13:         </section>
michael@13:         <section>
michael@12:                 <title><varname>branchlabel</varname> (string)</title>
michael@12:                 <para>
michael@12:                 This parameter determines which label i_enum_query() will use
michael@12:                 to branch off to the infrastructure ENUM tree.
michael@12:                 </para>
michael@12:                 <para>
michael@12:                 Default value is <quote>"i"</quote>
michael@12:                 </para>
michael@12:                 <example>
michael@13:                 <title>Setting branchlabel module parameter</title>
michael@12:                 <programlisting format="linespecific">
michael@12: modparam("enum", "branchlabel", "i")
michael@12: </programlisting>
michael@12:                 </example>
michael@12:         </section>
michael@12:         <section>
michael@12:                 <title><varname>bl_algorithm</varname> (string)</title>
michael@12:                 <para>
michael@12:                 This parameter determines which algorithm i_enum_query() will use
michael@12:                 to select the position in the DNS tree where the infrastructure tree
michael@12:                 branches off the user ENUM tree.
michael@12:                 </para>
michael@12:                 <para>
michael@12:                 If set to "cc", i_enum_query() will always inserts the
michael@12:                 label at the country-code level.
michael@12:                 Examples: i.1.e164.arpa, i.3.4.e164.arpa, i.2.5.3.e164.arpa
michael@12:                 </para>
michael@12:                 <para>
michael@12:                 If set to "txt", i_enum_query() will look for a TXT record at
michael@12:                 [branchlabel].[reverse-country-code].[i_enum_suffix] to indicate after how many digits the
michael@12:                 label should in inserted.
michael@12:                 <example>
michael@12:                 <title>Zone file example</title>
michael@12:                 <programlisting format="linespecific">
michael@12: i.1.e164.arpa.                     IN TXT   "4"
michael@12: 9.9.9.8.7.6.5.i.4.3.2.1.e164.arpa. IN NAPTR "NAPTR content for  +1 234 5678 999"
michael@12: </programlisting>
michael@12:                 </example>
michael@12:                 </para>
michael@12:                 <para>
michael@12:                 If set to "ebl", i_enum_query() will look for an EBL (ENUM Branch Label) record at
michael@12:                 [branchlabel].[reverse-country-code].[i_enum_suffix]. See http://www.ietf.org/internet-drafts/draft-lendl-enum-branch-location-record-00.txt for a description of that record and the
michael@12:                 meaning of the fields. The RR type for the EBL has not been allocated yet.
michael@12:                 This version of the code uses 65300. See resolve.h.
michael@12:                 <example>
michael@12:                 <title>Zone file example</title>
michael@12:                 <programlisting format="linespecific">
michael@12: i.1.e164.arpa.     TYPE65300  \# 14 (
michael@12:                               04    ; position
michael@12:                               01 69 ; separator
michael@12:                               04 65 31 36 34 04 61 72 70 61 00 ; e164.arpa
michael@12: ;                               )
michael@12: 9.9.9.8.7.6.5.i.4.3.2.1.e164.arpa. IN NAPTR "NAPTR content for  +1 234 5678 999"
michael@12: </programlisting>
michael@12:                 </example>
michael@12:                 </para>
michael@12: 
michael@12:                 <para>
michael@12:                 Default value is <quote>cc</quote>
michael@12:                 </para>
michael@12:                 <example>
michael@12:                 <title>Setting the bl_algorithm module parameter</title>
michael@12:                 <programlisting format="linespecific">
michael@12: modparam("enum", "bl_algorithm", "txt")
michael@12: </programlisting>
michael@12:                 </example>
michael@12:         </section>
michael@12: 
michael@12: 	</section>
michael@12: 
michael@12: 	<section>
michael@12: 	<title>Exported Functions</title>
michael@12: 	<section>
michael@12: 		<title>
michael@12: 		<function moreinfo="none">enum_query(["suffix"[,"service"]])</function>
michael@12: 		</title>
michael@12: 		<para>
michael@12: 		The function performs an enum query and rewrites the Request-URI with 
michael@12: 		the result of the query. See <xref linkend="sec-overview"/> for more 
michael@12: 		information.
michael@12: 		</para>
michael@12: 		<para>Meaning of the parameters is as follows:</para>
michael@12: 		<itemizedlist>
michael@12: 		<listitem>
michael@12: 			<para><emphasis>suffix</emphasis> - Suffix to be appended to the 
michael@12: 			domain name.
michael@12: 			</para>
michael@12: 		</listitem>
michael@12: 		<listitem>
michael@12: 			<para><emphasis>service</emphasis> - Service string to be used in 
michael@12: 			the service field.
michael@12: 			</para>
michael@12: 		</listitem>
michael@12: 		</itemizedlist>
michael@12: 		<para>
michael@12: 		This function can be used from REQUEST_ROUTE.
michael@12: 		</para>
michael@12: 		<example>
michael@12: 		<title><function moreinfo="none">enum_query</function> usage</title>
michael@12: 		<programlisting format="linespecific">
michael@12: ...
michael@12: # search for "e2u+sip" in freenum.org 
michael@12: enum_query("freenum.org.");
michael@12: ...
michael@12: # search for "e2u+sip" in default tree (configured as parameter)
michael@12: enum_query();
michael@12: ...
michael@12: # search for "e2u+voice:sip" in e164.arpa
michael@12: enum_query("e164.arpa.","voice");
michael@12: ...
michael@12: # search for service type "sip" or "voice:sip" or "video:sip"
michael@12: # note the '+' sign in front of the second parameter
michael@12: enum_query("e164.arpa.","+sip+voice:sip+video:sip");
michael@12: ...
michael@12: # quering for service sip and voice:sip
michael@12: enum_query("e164.arpa.");
michael@12: enum_query("e164.arpa.","voice");
michael@12: # or use instead
michael@12: enum_query("e164.arpa.","+sip+voice:sip");
michael@12: ...
michael@12: </programlisting>
michael@12: 		</example>
michael@12: 	</section>
michael@12: 
michael@12: 	<section>
michael@12: 		<title>
michael@12: 		<function moreinfo="none">enum_pv_query("pvar"[,"suffix"[,"service"]])</function>
michael@12: 		</title>
michael@12: 		<para>
michael@12: 		The function performs an enum query on E.164 number stored
michael@12: 		in its pseudo variable argument and rewrites the Request-URI with 
michael@12: 		the result of the query. See <xref linkend="sec-overview"/> for more 
michael@12: 		information.
michael@12: 		</para>
michael@12: 		<para>Meaning of the parameters is as follows:</para>
michael@12: 		<itemizedlist>
michael@12: 		<listitem>
michael@12: 			<para><emphasis>pvar</emphasis> - Pseudo
michael@12: 		variable that holds an E.164 number on which enum
michael@12: 		query is performed.
michael@12: 			</para>
michael@12: 		</listitem>
michael@12: 		<listitem>
michael@12: 			<para><emphasis>suffix</emphasis> - Suffix to be appended to the 
michael@12: 			domain name.
michael@12: 			</para>
michael@12: 		</listitem>
michael@12: 		<listitem>
michael@12: 			<para><emphasis>service</emphasis> - Service string to be used in 
michael@12: 			the service field.
michael@12: 			</para>
michael@12: 		</listitem>
michael@12: 		</itemizedlist>
michael@12: 		<para>
michael@12: 		This function can be used from REQUEST_ROUTE.
michael@12: 		</para>
michael@12: 		<example>
michael@12: 		<title><function moreinfo="none">enum_pv_query</function> usage</title>
michael@12: 		<programlisting format="linespecific">
michael@12: ...
michael@12: # search for "e2u+sip" in freenum.org 
michael@12: enum_pv_query("$avp(i:100)", "freenum.org.");
michael@12: ...
michael@12: # search for "e2u+sip" in default tree (configured as parameter)
michael@12: enum_pv_query("$fU");
michael@12: ...
michael@12: # search for "e2u+voice:sip" in e164.arpa
michael@12: enum_pv_query("$avp(i:100)","e164.arpa.","voice");
michael@12: ...
michael@12: # search for service type "sip" or "voice:sip" or "video:sip"
michael@12: # note the '+' sign in front of the second parameter
michael@12: enum_pv_query("$fU","e164.arpa.","+sip+voice:sip+video:sip");
michael@12: ...
michael@12: # quering for service sip and voice:sip
michael@12: enum_pv_query("$avp(i:100)","e164.arpa.");
michael@12: enum_pv_query("$avp(i:100)","e164.arpa.","voice");
michael@12: # or use instead
michael@12: enum_pv_query("$avp(i:100)","e164.arpa.","+sip+voice:sip");
michael@12: ...
michael@12: </programlisting>
michael@12: 		</example>
michael@12: 	</section>
michael@12: 
michael@12:         <section>
michael@12:                 <title>
michael@12:                 <function moreinfo="none">i_enum_query(["suffix"[,"service"]])</function>
michael@12:                 </title>
michael@12:                 <para>
michael@12:                 The function performs an enum query and rewrites the Request-URI with
michael@12:                 the result of the query. This the Infrastructure-ENUM version of enum_query().
michael@12:                 The only difference to enum_query() is in the calculation of the
michael@12:                 FQDN where NAPTR records are looked for.
michael@12:                 </para>
michael@12:                 <para>
michael@12:                 See ftp://ftp.rfc-editor.org/in-notes/internet-drafts/draft-haberler-carrier-enum-01.txt
michael@12:                 for the rationale behind this function.
michael@12:                 </para>
michael@12:         </section>
michael@12: 
michael@12: 	<section>
michael@13: 		<title>
michael@13: 		<function moreinfo="none">isn_query(["suffix"[,"service"]])</function>
michael@13: 		</title>
michael@13: 		<para>
michael@13: 		The function performs a ISN query and rewrites the Request-URI with 
michael@13: 		the result of the query. See <xref linkend="sec-overview"/> for more 
michael@13: 		information.
michael@13: 		</para>
michael@13: 		<para>Meaning of the parameters is as follows:</para>
michael@13: 		<itemizedlist>
michael@13: 		<listitem>
michael@13: 			<para><emphasis>suffix</emphasis> - Suffix to be appended to the 
michael@13: 			domain name.
michael@13: 			</para>
michael@13: 		</listitem>
michael@13: 		<listitem>
michael@13: 			<para><emphasis>service</emphasis> - Service string to be used in 
michael@13: 			the service field.
michael@13: 			</para>
michael@13: 		</listitem>
michael@13: 		</itemizedlist>
michael@13: 		<para>
michael@13: 			This function can be used from REQUEST_ROUTE.
michael@13: 		</para>
michael@13: 		<para>
michael@15: 			See ftp://ftp.ietf.org/rfc/rfc3872.txt and
michael@15: 			ftp://ftp.ietf.org/rfc/rfc2871.txt for information
michael@13: 			regarding the ITAD part of the ISN string.
michael@13: 		</para>
michael@13: 		<example>
michael@13: 		<title><function moreinfo="none">isn_query</function> usage</title>
michael@13: 		<programlisting format="linespecific">
michael@13: ...
michael@13: # search for "e2u+sip" in freenum.org 
michael@13: isn_query("freenum.org.");
michael@13: ...
michael@13: # search for "e2u+sip" in default tree (configured as parameter)
michael@13: isn_query();
michael@13: ...
michael@13: # search for "e2u+voice:sip" in freenum.org
michael@13: isn_query("freenum.org.","voice");
michael@13: ...
michael@13: </programlisting>
michael@13: 		</example>
michael@13: 	</section>
michael@13: 
michael@13: 	<section>
michael@12: 		<title><function moreinfo="none">is_from_user_enum()</function></title>
michael@12: 		<para>
michael@12: 		Checks if the user part of from <abbrev>URI</abbrev>
michael@12: 		is found in an enum lookup.
michael@12: 		Returns 1 if yes and -1 if not.
michael@12: 		</para>
michael@12: 		<para>
michael@12: 		This function can be used from REQUEST_ROUTE.
michael@12: 		</para>
michael@12: 		<example>
michael@12: 		<title><function moreinfo="none">is_from_user_enum</function> usage</title>
michael@12: 		<programlisting format="linespecific">
michael@12: ...
michael@12: if (is_from_user_enum()) {
michael@12: 	....
michael@12: };
michael@12: ...
michael@12: </programlisting>
michael@12: 		</example>
michael@12: 	</section>
michael@12: 	</section>
michael@12: </chapter>
michael@12: