Doxygen updates

modules/enum/README

@@ -10,30 +10,29 @@ Otmar Lendl
 
    Copyright © 2002, 2003 Juha Heinanen
    Revision History
-   Revision $Revision$ $Date: 2008-03-08 00:03:56 +0100
-                              (Sa, 08 Mär 2008) $
-     __________________________________________________________
+   Revision $Revision$ $Date$
+     __________________________________________________________________
 
    Table of Contents
 
    1. Admin Guide
 
-        1.1. Overview
-        1.2. Dependencies
-        1.3. Exported Parameters
+        1. Overview
+        2. Dependencies
+        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)
+              3.1. domain_suffix (string)
+              3.2. tel_uri_params (string)
+              3.3. i_enum_suffix (string)
+              3.4. branchlabel (string)
+              3.5. bl_algorithm (string)
 
-        1.4. Exported Functions
+        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()
+              4.1. enum_query(["suffix"[,"service"]])
+              4.2. enum_pv_query("pvar"[,"suffix"[,"service"]])
+              4.3. i_enum_query(["suffix"[,"service"]])
+              4.4. is_from_user_enum()
 
    List of Examples
 
@@ -50,105 +49,124 @@ Otmar Lendl
 
 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):
+   Table of Contents
+
+   1. Overview
+   2. Dependencies
+   3. Exported Parameters
+
+        3.1. domain_suffix (string)
+        3.2. tel_uri_params (string)
+        3.3. i_enum_suffix (string)
+        3.4. branchlabel (string)
+        3.5. bl_algorithm (string)
+
+   4. Exported Functions
+
+        4.1. enum_query(["suffix"[,"service"]])
+        4.2. enum_pv_query("pvar"[,"suffix"[,"service"]])
+        4.3. i_enum_query(["suffix"[,"service"]])
+        4.4. is_from_user_enum()
+
+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 Request URI 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 enum NAPTR
+   records. From the possible responses 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 the regular expression of the most preferred NAPTR record
+   to 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.
+
+2. Dependencies
+
+   The module depends on the following modules (in other words the listed
+   modules must be loaded before this module):
      * No dependencies.
 
-1.3. Exported Parameters
+3. Exported Parameters
 
-1.3.1. domain_suffix (string)
+   3.1. domain_suffix (string)
+   3.2. tel_uri_params (string)
+   3.3. i_enum_suffix (string)
+   3.4. branchlabel (string)
+   3.5. bl_algorithm (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.
+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)
+3.2. tel_uri_params (string)
 
-   A string whose contents is appended to each new tel URI in the
-   request as tel URI parameters.
+   A string whose contents is appended to each new tel URI in the request
+   as tel URI parameters.
 
 Note
 
-   Currently Kamailio does not support tel URIs. This means that
-   at present tel_uri_params is appended as URI parameters to
-   every URI.
+   Currently Kamailio 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)
+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.
@@ -158,66 +176,67 @@ modparam("enum", "tel_uri_params", ";npdi")
    Example 1.3. Setting i_enum_suffix module parameter
 modparam("enum", "i_enum_suffix", "e1234.arpa.")
 
-1.3.4. branchlabel (string)
+3.4. branchlabel (string)
 
-   This parameter determines which label i_enum_query() will use
-   to branch off to the infrastructure ENUM tree.
+   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)
+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.
+   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 "cc", i_enum_query() will always insert 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.
+   [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.
+9.9.9.8.7.6.5.i.4.3.2.1.e164.arpa. IN NAPTR "NAPTR content for  +1 234 5678 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-location-re
+   cord-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
+                              04 65 31 36 34 04 61 72 70 61 00 ; e164.arpa
 ;                               )
-9.9.9.8.7.6.5.i.4.3.2.1.e164.arpa. IN NAPTR "NAPTR content for  +1 234 5
-678 999"
+9.9.9.8.7.6.5.i.4.3.2.1.e164.arpa. IN NAPTR "NAPTR content for  +1 234 5678 999"
 
    Default value is "cc"
 
    Example 1.7. Setting the bl_algorithm module parameter
 modparam("enum", "bl_algorithm", "txt")
 
-1.4. Exported Functions
+4. Exported Functions
+
+   4.1. enum_query(["suffix"[,"service"]])
+   4.2. enum_pv_query("pvar"[,"suffix"[,"service"]])
+   4.3. i_enum_query(["suffix"[,"service"]])
+   4.4. is_from_user_enum()
 
-1.4.1.  enum_query(["suffix"[,"service"]])
+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.
+   The function performs an enum query and rewrites the Request-URI with
+   the result of the query. See Section 1, "Overview" for more
+   information.
 
    Meaning of the parameters is as follows:
      * suffix - Suffix to be appended to the domain name.
@@ -247,16 +266,15 @@ enum_query("e164.arpa.","voice");
 enum_query("e164.arpa.","+sip+voice:sip");
 ...
 
-1.4.2.  enum_pv_query("pvar"[,"suffix"[,"service"]])
+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.
+   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, "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.
+     * 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.
 
@@ -284,22 +302,21 @@ enum_pv_query("$avp(i:100)","e164.arpa.","voice");
 enum_pv_query("$avp(i:100)","e164.arpa.","+sip+voice:sip");
 ...
 
-1.4.3.  i_enum_query(["suffix"[,"service"]])
+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.
+   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.
+   ftp://ftp.rfc-editor.org/in-notes/internet-drafts/draft-haberler-carrie
+   r-enum-01.txt for the rationale behind this function.
 
-1.4.4. is_from_user_enum()
+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.
+   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.
 

modules/enum/doc/enum_admin.xml

@@ -19,7 +19,7 @@
 	<para>
 		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 
+		assume that the Request URI 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, 
@@ -34,7 +34,7 @@
 	<para>
 		After forming the domain name, 
 		<function moreinfo="none">enum_query</function> queries
-		DNS for its NAPTR records. From the possible response 
+		DNS for enum NAPTR records. From the possible responses
 		<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" or 
@@ -45,11 +45,11 @@
 		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 
+		Request URI by applying the regular expression of the most preferred NAPTR record 
+		to 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 
+		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 
@@ -94,7 +94,7 @@
 	<section>
 	<title>Dependencies</title>
 	<para>
-		The module depends on the following modules (in the other words the 
+		The module depends on the following modules (in other words the 
 		listed modules must be loaded before this module):
 		<itemizedlist>
 		<listitem>
@@ -186,7 +186,7 @@ modparam("enum", "branchlabel", "i")
                 branches off the user ENUM tree.
                 </para>
                 <para>
-                If set to "cc", i_enum_query() will always inserts the
+                If set to "cc", i_enum_query() will always insert the
                 label at the country-code level.
                 Examples: i.1.e164.arpa, i.3.4.e164.arpa, i.2.5.3.e164.arpa
                 </para>

modules/enum/enum.c

@@ -23,6 +23,31 @@
  *
  */
 
+/*!
+ * \file
+ * \brief SIP-router enum :: Enum and E164 related functions (module interface)
+ * \ingroup enum
+ * Module: \ref enum
+ */
+
+/*! \defgroup enum Enum and E.164-related functions
+
+ *  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 Request URI 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.
+ */
+
+
+
 #include <stdlib.h>
 
 #include "enum.h"

modules/enum/enum.h

@@ -21,6 +21,12 @@
  * along with this program; if not, write to the Free Software 
  * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
  */
+/*!
+ * \file
+ * \brief SIP-router enum :: Header file for Enum and E164 related functions (module interface)
+ * \ingroup enum
+ * Module: \ref enum
+ */
 
 
 #ifndef ENUM_H

modules/enum/enum_mod.c

@@ -28,6 +28,13 @@
  * 2003-12-15: added suffix parameter to enum_query (jh)
  */
 
+/*!
+ * \file
+ * \brief SIP-router enum :: Enum and E164 related functions 
+ * \ingroup enum
+ * Module: \ref enum
+ */
+
 
 #include "enum_mod.h"
 #include <stdio.h>

modules/enum/enum_mod.h

@@ -22,6 +22,13 @@
  * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
  */
 
+/*!
+ * \file
+ * \brief SIP-router enum :: Enum and E164 related functions (module headers)
+ * \ingroup enum
+ * Module: \ref enum
+ */
+
 
 #ifndef ENUM_MOD_H
 #define ENUM_MOD_H