enum_user.sgml

用来作为linux中SIP SERVER,完成VOIP网络电话中服务器的功能

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

<chapter>
    <chapterinfo>
	<revhistory>
	    <revision>
		<revnumber>$Revision: 1.2 $</revnumber>
		<date>$Date: 2004/09/05 16:09:18 $</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 [phone], 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" (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>
	    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>
    </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>
	    <example>
		<title><function moreinfo="none">enum_query</function> usage</title>
		<programlisting format="linespecific">
...
enum_query("freenum.org.");
...
</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:
-->