diff -r e1a27284134f -r a3ac912f2857 opensips/modules/enum/README
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/opensips/modules/enum/README	Mon Jan 18 19:47:23 2010 +0100
@@ -0,0 +1,311 @@
+Enum Module
+
+Juha Heinanen
+
+   <jh@song.fi>
+
+Otmar Lendl
+
+   <lendl@nic.at>
+
+   Copyright © 2002, 2003 Juha Heinanen
+   Revision History
+   Revision $Revision: 5906 $ $Date: 2009-07-21 10:45:05 +0300
+                              (Tue, 21 Jul 2009) $
+     __________________________________________________________
+
+   Table of Contents
+
+   1. Admin 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.3.3. i_enum_suffix (string)
+              1.3.4. branchlabel (string)
+              1.3.5. bl_algorithm (string)
+
+        1.4. Exported Functions
+
+              1.4.1. enum_query(["suffix"[,"service"]])
+              1.4.2. enum_pv_query("pvar"[,"suffix"[,"service"]])
+              1.4.3. i_enum_query(["suffix"[,"service"]])
+              1.4.4. is_from_user_enum()
+
+   List of Examples
+
+   1.1. Setting domain_suffix module parameter
+   1.2. Setting tel_uri_params module parameter
+   1.3. Setting i_enum_suffix module parameter
+   1.4. Setting brachlabel module parameter
+   1.5. Zone file example
+   1.6. Zone file example
+   1.7. Setting the bl_algorithm module parameter
+   1.8. enum_query usage
+   1.9. enum_pv_query usage
+   1.10. is_from_user_enum usage
+
+Chapter 1. Admin Guide
+
+1.1. Overview
+
+   Enum module implements [i_]enum_query functions that make an
+   enum query based on the user part of the current Request-URI.
+   These functions assume 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.". i_enum_query operates in a
+   similar fashion. The only difference is that it adds a label
+   (default "i") to branch off from the default, user-ENUM tree to
+   an infrastructure ENUM tree.
+
+   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 something else. The
+   function enum_pv_query mimics the behavior of the enum_query
+   function except the E.164 number in its pseudo variable
+   argument 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_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 OpenSIPS 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.3.3. i_enum_suffix (string)
+
+   The domain suffix to be used for i_enum_query() lookups. Can be
+   overridden by a parameter to i_enum_query.
+
+   Default value is "e164.arpa."
+
+   Example 1.3. Setting i_enum_suffix module parameter
+modparam("enum", "i_enum_suffix", "e1234.arpa.")
+
+1.3.4. branchlabel (string)
+
+   This parameter determines which label i_enum_query() will use
+   to branch off to the infrastructure ENUM tree.
+
+   Default value is ""i""
+
+   Example 1.4. Setting brachlabel module parameter
+modparam("enum", "branchlabel", "i")
+
+1.3.5. bl_algorithm (string)
+
+   This parameter determines which algorithm i_enum_query() will
+   use to select the position in the DNS tree where the
+   infrastructure tree branches off the user ENUM tree.
+
+   If set to "cc", i_enum_query() will always inserts the label at
+   the country-code level. Examples: i.1.e164.arpa,
+   i.3.4.e164.arpa, i.2.5.3.e164.arpa
+
+   If set to "txt", i_enum_query() will look for a TXT record at
+   [branchlabel].[reverse-country-code].[i_enum_suffix] to
+   indicate after how many digits the label should in inserted.
+
+   Example 1.5. Zone file example
+i.1.e164.arpa.                     IN TXT   "4"
+9.9.9.8.7.6.5.i.4.3.2.1.e164.arpa. IN NAPTR "NAPTR content for  +1 234 5
+678 999"
+
+   If set to "ebl", i_enum_query() will look for an EBL (ENUM
+   Branch Label) record at
+   [branchlabel].[reverse-country-code].[i_enum_suffix]. See
+   http://www.ietf.org/internet-drafts/draft-lendl-enum-branch-loc
+   ation-record-00.txt for a description of that record and the
+   meaning of the fields. The RR type for the EBL has not been
+   allocated yet. This version of the code uses 65300. See
+   resolve.h.
+
+   Example 1.6. Zone file example
+i.1.e164.arpa.     TYPE65300  \# 14 (
+                              04    ; position
+                              01 69 ; separator
+                              04 65 31 36 34 04 61 72 70 61 00 ; e164.ar
+pa
+;                               )
+9.9.9.8.7.6.5.i.4.3.2.1.e164.arpa. IN NAPTR "NAPTR content for  +1 234 5
+678 999"
+
+   Default value is "cc"
+
+   Example 1.7. Setting the bl_algorithm module parameter
+modparam("enum", "bl_algorithm", "txt")
+
+1.4. Exported Functions
+
+1.4.1.  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,
+   "Overview" 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.8. 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_pv_query("pvar"[,"suffix"[,"service"]])
+
+   The function performs an enum query on E.164 number stored in
+   its pseudo variable argument and rewrites the Request-URI with
+   the result of the query. See Section 1.1, "Overview" for more
+   information.
+
+   Meaning of the parameters is as follows:
+     * pvar - Pseudo variable that holds an E.164 number on which
+       enum query is performed.
+     * 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.9. enum_pv_query usage
+...
+# search for "e2u+sip" in freenum.org
+enum_pv_query("$avp(i:100)", "freenum.org.");
+...
+# search for "e2u+sip" in default tree (configured as parameter)
+enum_pv_query("$fU");
+...
+# search for "e2u+voice:sip" in e164.arpa
+enum_pv_query("$avp(i:100)","e164.arpa.","voice");
+...
+# search for service type "sip" or "voice:sip" or "video:sip"
+# note the '+' sign in front of the second parameter
+enum_pv_query("$fU","e164.arpa.","+sip+voice:sip+video:sip");
+...
+# quering for service sip and voice:sip
+enum_pv_query("$avp(i:100)","e164.arpa.");
+enum_pv_query("$avp(i:100)","e164.arpa.","voice");
+# or use instead
+enum_pv_query("$avp(i:100)","e164.arpa.","+sip+voice:sip");
+...
+
+1.4.3.  i_enum_query(["suffix"[,"service"]])
+
+   The function performs an enum query and rewrites the
+   Request-URI with the result of the query. This the
+   Infrastructure-ENUM version of enum_query(). The only
+   difference to enum_query() is in the calculation of the FQDN
+   where NAPTR records are looked for.
+
+   See
+   ftp://ftp.rfc-editor.org/in-notes/internet-drafts/draft-haberle
+   r-carrier-enum-01.txt for the rationale behind this function.
+
+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.10. is_from_user_enum usage
+...
+if (is_from_user_enum()) {
+        ....
+};
+...