Enum Module

Juha Heinanen

   Copyright  2002, 2003 Juha Heinanen
     _________________________________________________________

   Table of Contents
   1. User's Guide

        1.1. Overview
        1.2. Dependencies
        1.3. Exported Parameters

              1.3.1. domain_suffix (string)
              1.3.2. tel_uri_params (string)

        1.4. Exported Functions

              1.4.1. enum_query(),enum_query("suffix"),
                      enum_query("suffix", "service")

              1.4.2. enum_fquery(),enum_fquery("suffix"),
                      enum_fquery("suffix", "service")

              1.4.3. is_from_user_e164()
              1.4.4. is_from_user_enum()

   2. Developer's Guide
   3. Frequently Asked Questions

   List of Examples
   1-1. Setting domain_suffix module parameter
   1-2. Setting tel_uri_params module parameter
   1-3. enum_query usage
   1-4. enum_fquery usage
   1-5. is_from_user_e164 usage
   1-6. is_from_user_enum usage
     _________________________________________________________

Chapter 1. User's Guide

1.1. Overview

   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 enum_query forms a domain name, where the digits are in
   reverse order and separated by dots followed by domain suffix
   that by default is "e164.arpa.". For example, if the user part
   is +35831234567, the domain name will be
   "7.6.5.4.3.2.1.3.8.5.3.e164.arpa.".

   After forming the domain name, enum_query queries DNS for its
   NAPTR records. From the possible response enum_query 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!.

   Then enum_query sorts the chosen NAPTR records based on their
   <order, preference>. After sorting, enum_query 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, enum_query appends to it as tel URI parameters the
   value of tel_uri_params module parameter. Finally, enum_query
   associates a q value with each new URI based on the <order,
   preference> of the corresponding NAPTR record.

   When using enum_query without any parameters, it searches for
   NAPTRs with service type "e2u+sip" in the default enum tree.
   When using enum_query with a single parameter, this parameter
   will be used as enum tree. When using enum_query 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.

   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
   "From:" tag, analogous to source based policy routing in the
   ip world. The function enum_fquery mimics the behaviour of the
   enum_query function except the user part of the "From:" 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.

   Enum query returns 1 if the current Request URI was replaced
   and -1 if not.

   Enum module also implements is_from_user_e164 function that
   checks if the user part of from URI is an E164 number.

   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.
     _________________________________________________________

1.2. Dependencies

   The module depends on the following modules (in the other
   words the listed modules must be loaded before this module):

     * No dependencies.
     _________________________________________________________

1.3. Exported Parameters

1.3.1. domain_suffix (string)

   The domain suffix to be added to the domain name obtained from
   the digits of an E164 number. Can be overridden by a parameter
   to enum_query.

   Default value is "e164.arpa."

   Example 1-1. Setting domain_suffix module parameter
modparam("enum", "domain_suffix", "e1234.arpa.")
     _________________________________________________________

1.3.2. tel_uri_params (string)

   A string whose contents is appended to each new tel URI in the
   request as tel URI parameters.

   Note

   Currently OpenSER does not support tel URIs. This means that
   at present tel_uri_params is appended as URI parameters to
   every URI.

   Default value is ""

   Example 1-2. Setting tel_uri_params module parameter
modparam("enum", "tel_uri_params", ";npdi")
     _________________________________________________________

1.4. Exported Functions

1.4.1. enum_query(),enum_query("suffix"), enum_query("suffix",
"service")

   The function performs an enum query and rewrites the
   Request-URI with the result of the query. See Section 1.1> for
   more information.

   Meaning of the parameters is as follows:

     * suffix - Suffix to be appended to the domain name.
     * service - Service string to be used in the service field.

   This function can be used from REQUEST_ROUTE.

   Example 1-3. enum_query usage
...
# 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");
...
     _________________________________________________________

1.4.2. enum_fquery(),enum_fquery("suffix"), enum_fquery("suffix",
"service")

   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 Section 1.1> for more information.

   Meaning of the parameters is as follows:

     * suffix - Suffix to be appended to the domain name.
     * service - Service string to be used in the service field.

   This function can be used from REQUEST_ROUTE.

   Example 1-4. enum_fquery usage
...
# 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");
...
     _________________________________________________________

1.4.3. is_from_user_e164()

   Checks if the user part of from URI an E164 number of the form
   +[0-9]{2,15}. Returns 1 if yes and -1 if not.

   This function can be used from REQUEST_ROUTE.

   Example 1-5. is_from_user_e164 usage
...
if (is_from_user_e164()) {
        ....
};
...
     _________________________________________________________

1.4.4. is_from_user_enum()

   Checks if the user part of from URI is found in an enum
   lookup. Returns 1 if yes and -1 if not.

   This function can be used from REQUEST_ROUTE.

   Example 1-6. is_from_user_enum usage
...
if (is_from_user_enum()) {
        ....
};
...
     _________________________________________________________

Chapter 2. Developer's Guide

   The module does not provide any API to use in other OpenSER
   modules.
     _________________________________________________________

Chapter 3. Frequently Asked Questions

   3.1. Where can I find more about OpenSER?
   3.2. Where can I post a question about this module?
   3.3. How can I report a bug?

   3.1. Where can I find more about OpenSER?

   Take a look at http://openser.org/.

   3.2. Where can I post a question about this module?

   First at all check if your question was already answered on
   one of our mailing lists:

     * User Mailing List -
       http://openser.org/cgi-bin/mailman/listinfo/users
     * Developer Mailing List -
       http://openser.org/cgi-bin/mailman/listinfo/devel

   E-mails regarding any stable OpenSER release should be sent to
   <users@openser.org> and e-mails regarding development versions
   should be sent to <devel@openser.org>.

   If you want to keep the mail private, send it to
   <team@openser.org>.

   3.3. How can I report a bug?

   Please follow the guidelines provided at:
   http://sourceforge.net/tracker/?group_id=139143.