Doxygen updates

modules_k/siputils/checks.c

@@ -5,14 +5,14 @@
  *
  * Copyright (C) 2001-2003 FhG Fokus
  *
- * This file is part of Kamailio, a free SIP server.
+ * This file is part of SIP-router, a free SIP server.
  *
- * Kamailio is free software; you can redistribute it and/or modify
+ * SIP-router is free software; you can redistribute it and/or modify
  * it under the terms of the GNU General Public License as published by
  * the Free Software Foundation; either version 2 of the License, or
  * (at your option) any later version
  *
- * Kamailio is distributed in the hope that it will be useful,
+ * SIP-router is distributed in the hope that it will be useful,
  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  * GNU General Public License for more details.
@@ -28,6 +28,14 @@
  * 2004-04-14: uri_param and add_uri_param introduced (jih)
  */
 
+/*!
+ * \file
+ * \brief SIP-utils :: Various URI checks and Request URI manipulation
+ * \ingroup siputils
+ * - Module; \ref siputils
+ */
+
+
 #include <string.h>
 #include "../../str.h"
 #include "../../dprint.h"               /* Debugging */

modules_k/siputils/checks.h

@@ -5,14 +5,14 @@
  *
  * Copyright (C) 2001-2003 FhG Fokus
  *
- * This file is part of Kamailio, a free SIP server.
+ * This file is part of SIP-router, a free SIP server.
  *
- * Kamailio is free software; you can redistribute it and/or modify
+ * SIP-router is free software; you can redistribute it and/or modify
  * it under the terms of the GNU General Public License as published by
  * the Free Software Foundation; either version 2 of the License, or
  * (at your option) any later version
  *
- * Kamailio is distributed in the hope that it will be useful,
+ * SIP-router is distributed in the hope that it will be useful,
  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  * GNU General Public License for more details.
@@ -27,6 +27,14 @@
  * 2004-04-14 uri_param and add_uri_param introduced (jih)
  */
 
+/*!
+ * \file
+ * \brief SIP-utils :: Various URI checks and Request URI manipulation
+ * \ingroup siputils
+ * - Module; \ref siputils
+ */
+
+
 
 #ifndef CHECKS_H
 #define CHECKS_H

modules_k/siputils/contact_ops.c

@@ -5,14 +5,14 @@
  *
  * Copyright (C) 2001-2003 FhG Fokus
  *
- * This file is part of Kamailio, a free SIP server.
+ * This file is part of SIP-router, a free SIP server.
  *
- * Kamailio is free software; you can redistribute it and/or modify
+ * SIP-router is free software; you can redistribute it and/or modify
  * it under the terms of the GNU General Public License as published by
  * the Free Software Foundation; either version 2 of the License, or
  * (at your option) any later version
  *
- * Kamailio is distributed in the hope that it will be useful,
+ * SIP-router is distributed in the hope that it will be useful,
  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  * GNU General Public License for more details.
@@ -26,6 +26,14 @@
  *  2003-04-07 first version.  
  */
 
+/*!
+ * \file
+ * \brief SIP-utils :: Mangler module
+ * \ingroup siputils
+ * - Module; \ref siputils
+ */
+
+
 #define STRICT_CHECK 1
 
 #include "contact_ops.h"

modules_k/siputils/contact_ops.h

@@ -5,14 +5,14 @@
  *
  * Copyright (C) 2001-2003 FhG Fokus
  *
- * This file is part of Kamailio, a free SIP server.
+ * This file is part of SIP-router, a free SIP server.
  *
- * Kamailio is free software; you can redistribute it and/or modify
+ * SIP-router is free software; you can redistribute it and/or modify
  * it under the terms of the GNU General Public License as published by
  * the Free Software Foundation; either version 2 of the License, or
  * (at your option) any later version
  *
- * Kamailio is distributed in the hope that it will be useful,
+ * SIP-router is distributed in the hope that it will be useful,
  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  * GNU General Public License for more details.
@@ -26,6 +26,16 @@
  *  2003-04-07 first version.  
  */
 
+/*!
+ * \file
+ * \brief SIP-utils :: Mangler module
+ * \ingroup siputils
+ * - Module; \ref siputils
+ *
+ * \todo :decode2format unpleasant
+ */
+
+
 /* TODO :decode2format unpleasant */
 
 #ifndef CONTACT_OPS_H

modules_k/siputils/options.c

@@ -5,14 +5,14 @@
  *
  * Copyright (C) 2001-2003 FhG Fokus
  *
- * This file is part of Kamailio, a free SIP server.
+ * This file is part of SIP-router, a free SIP server.
  *
- * Kamailio is free software; you can redistribute it and/or modify
+ * SIP-router is free software; you can redistribute it and/or modify
  * it under the terms of the GNU General Public License as published by
  * the Free Software Foundation; either version 2 of the License, or
  * (at your option) any later version
  *
- * Kamailio is distributed in the hope that it will be useful,
+ * SIP-router is distributed in the hope that it will be useful,
  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  * GNU General Public License for more details.
@@ -28,13 +28,9 @@
 
 /*!
  * \file siputils/options.c
- * \brief Options reply modules
- * \ingroup options
- * Module: \ref options
- */
-
-/*!
- * \defgroup options OPTIONS :: Reply to OPTION pokes
+ * \brief SIP-utils :: Options reply modules
+ * \ingroup siputils
+ * Module: \ref siputils
  */
 
 #ifdef EXTRA_DEBUG

modules_k/siputils/options.h

@@ -5,14 +5,14 @@
  *
  * Copyright (C) 2001-2003 FhG Fokus
  *
- * This file is part of Kamailio, a free SIP server.
+ * This file is part of SIP-router, a free SIP server.
  *
- * Kamailio is free software; you can redistribute it and/or modify
+ * SIP-router is free software; you can redistribute it and/or modify
  * it under the terms of the GNU General Public License as published by
  * the Free Software Foundation; either version 2 of the License, or
  * (at your option) any later version
  *
- * Kamailio is distributed in the hope that it will be useful,
+ * SIP-router is distributed in the hope that it will be useful,
  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  * GNU General Public License for more details.
@@ -24,9 +24,9 @@
 
 /*!
  * \file siputils/options.c
- * \brief Options reply modules
- * \ingroup options
- * Module: \ref options
+ * \brief SIP-utils :: Options reply modules
+ * \ingroup siputils
+ * Module: \ref siputils
  */
 
 #ifndef OPT_RPL_H

modules_k/siputils/ring.c

@@ -3,14 +3,14 @@
  *
  * Copyright (C) 2008-2009 1&1 Internet AG
  *
- * This file is part of Kamailio, a free SIP server.
+ * This file is part of SIP-router, a free SIP server.
  *
- * Kamailio is free software; you can redistribute it and/or modify
+ * SIP-router is free software; you can redistribute it and/or modify
  * it under the terms of the GNU General Public License as published by
  * the Free Software Foundation; either version 2 of the License, or
  * (at your option) any later version
  *
- * Kamailio is distributed in the hope that it will be useful,
+ * SIP-router is distributed in the hope that it will be useful,
  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  * GNU General Public License for more details.
@@ -22,16 +22,15 @@
 
 /**
  * \file
- * \brief Only allow one 183 message per call-id
- * \ingroup utils
- * - Module; \ref utils
- */
-
-/*!
- * \defgroup utils UTILS :: Ringing functionality
- * In a parallel forking scenario you get several 183s with SDP. You don't want
+ * \brief SIP-utils :: Only allow one 183 message per call-id
+ * \ingroup siputils
+ * - Module; \ref siputils
+ *
+ * \section ring_utils UTILS :: Ringing functionality
+ *
+ * In a parallel forking scenario you may get several 183s with SDP. You don't want
  * that your customers hear more than one ringtone or answer machine in parallel
- * on the phone. So its necessary to drop the 183 in this cases and send a 180 instead.
+ * on the phone. So its necessary to drop the 183 in these cases and send a 180 instead.
  */
 
 

modules_k/siputils/ring.h

@@ -3,14 +3,14 @@
  *
  * Copyright (C) 2008-2009 1&1 Internet AG
  *
- * This file is part of Kamailio, a free SIP server.
+ * This file is part of SIP-router, a free SIP server.
  *
- * Kamailio is free software; you can redistribute it and/or modify
+ * SIP-router is free software; you can redistribute it and/or modify
  * it under the terms of the GNU General Public License as published by
  * the Free Software Foundation; either version 2 of the License, or
  * (at your option) any later version
  *
- * Kamailio is distributed in the hope that it will be useful,
+ * SIP-router is distributed in the hope that it will be useful,
  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  * GNU General Public License for more details.
@@ -22,9 +22,9 @@
 
 /**
  * \file
- * \brief Module with several utiltity functions related to SIP messages handling
- * \ingroup utils
- * - Module; \ref utils
+ * \brief SIP-utils :: Module with several utiltity functions related to SIP messages handling
+ * \ingroup siputils
+ * - Module; \ref siputils
  */
 
 #ifndef RING_H

modules_k/siputils/sipops.c

@@ -5,14 +5,14 @@
  *
  * Copyright (C) 2001-2003 FhG Fokus
  *
- * This file is part of Kamailio, a free SIP server.
+ * This file is part of SIP-router, a free SIP server.
  *
- * Kamailio is free software; you can redistribute it and/or modify
+ * SIP-router is free software; you can redistribute it and/or modify
  * it under the terms of the GNU General Public License as published by
  * the Free Software Foundation; either version 2 of the License, or
  * (at your option) any later version
  *
- * Kamailio is distributed in the hope that it will be useful,
+ * SIP-router is distributed in the hope that it will be useful,
  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  * GNU General Public License for more details.
@@ -23,6 +23,14 @@
  *
  */
 
+/*!
+ * \file
+ * \brief SIP-utils :: Mangler Module
+ * \ingroup siputils
+ * - Module; \ref siputils
+ */
+
+
 #include "../../mod_fix.h"
 #include "../../lib/kcore/cmpapi.h"
 

modules_k/siputils/sipops.h

@@ -5,14 +5,14 @@
  *
  * Copyright (C) 2001-2003 FhG Fokus
  *
- * This file is part of Kamailio, a free SIP server.
+ * This file is part of SIP-router, a free SIP server.
  *
- * Kamailio is free software; you can redistribute it and/or modify
+ * SIP-router is free software; you can redistribute it and/or modify
  * it under the terms of the GNU General Public License as published by
  * the Free Software Foundation; either version 2 of the License, or
  * (at your option) any later version
  *
- * Kamailio is distributed in the hope that it will be useful,
+ * SIP-router is distributed in the hope that it will be useful,
  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  * GNU General Public License for more details.
@@ -23,6 +23,14 @@
  *
  */
 
+/*!
+ * \file
+ * \brief SIP-utils ::  URI Operations
+ * \ingroup siputils
+ * - Module; \ref siputils
+ */
+
+
 #ifndef _SIPOPS_H_
 #define _SIPOPS_H_
 

modules_k/siputils/siputils.c

@@ -4,14 +4,14 @@
  * Copyright (C) 2008-2009 1&1 Internet AG
  * Copyright (C) 2001-2003 FhG Fokus
  *
- * This file is part of Kamailio, a free SIP server.
+ * This file is part of SIP-router, a free SIP server.
  *
- * Kamailio is free software; you can redistribute it and/or modify
+ * SIP-router is free software; you can redistribute it and/or modify
  * it under the terms of the GNU General Public License as published by
  * the Free Software Foundation; either version 2 of the License, or
  * (at your option) any later version
  *
- * Kamailio is distributed in the hope that it will be useful,
+ * SIP-router is distributed in the hope that it will be useful,
  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  * GNU General Public License for more details.
@@ -21,15 +21,38 @@
  * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
  */
 
-/**
+/*!
  * \file
  * \brief Module with several utiltity functions related to SIP messages handling
- * \ingroup utils
- * - Module; \ref utils
+ * \ingroup siputils
+ * - Module; \ref siputils
  */
 
 /*!
- * \defgroup utils UTILS :: Module definitions
+ * \defgroup siputils UTILS :: Various SIP message handling functions
+ *
+ * \note A Kamailio module (modules_k)
+ *
+   This module implement various functions and checks related to
+   SIP message handling and URI handling.
+
+   It offers some functions related to handle ringing. In a
+   parallel forking scenario you get several 183s with SDP. You
+   don't want that your customers hear more than one ringtone or
+   answer machine in parallel on the phone. So its necessary to
+   drop the 183 in this cases and send a 180 instead.
+
+   This module provides a function to answer OPTIONS requests
+   which are directed to the server itself. This means an OPTIONS
+   request which has the address of the server in the request
+   URI, and no username in the URI. The request will be answered
+   with a 200 OK which the capabilities of the server.
+
+   To answer OPTIONS request directed to your server is the
+   easiest way for is-alive-tests on the SIP (application) layer
+   from remote (similar to ICMP echo requests, also known as
+   "ping", on the network layer).
+
  */
 
 #include <assert.h>

modules_k/siputils/utils.c

@@ -5,14 +5,14 @@
  *
  * Copyright (C) 2001-2003 FhG Fokus
  *
- * This file is part of Kamailio, a free SIP server.
+ * This file is part of SIP-router, a free SIP server.
  *
- * Kamailio is free software; you can redistribute it and/or modify
+ * SIP-router is free software; you can redistribute it and/or modify
  * it under the terms of the GNU General Public License as published by
  * the Free Software Foundation; either version 2 of the License, or
  * (at your option) any later version
  *
- * Kamailio is distributed in the hope that it will be useful,
+ * SIP-router is distributed in the hope that it will be useful,
  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  * GNU General Public License for more details.
@@ -26,6 +26,14 @@
  *  2003-04-07 first version.  
  */
 
+/*!
+ * \file
+ * \brief SIP-utils :: Mangler
+ * \ingroup siputils
+ * - Module; \ref siputils
+ */
+
+
 #include "utils.h"
 
 #include "../../parser/msg_parser.h"	/* struct sip_msg */

modules_k/siputils/utils.h

@@ -5,14 +5,14 @@
  *
  * Copyright (C) 2001-2003 FhG Fokus
  *
- * This file is part of Kamailio, a free SIP server.
+ * This file is part of SIP-router, a free SIP server.
  *
- * Kamailio is free software; you can redistribute it and/or modify
+ * SIP-router is free software; you can redistribute it and/or modify
  * it under the terms of the GNU General Public License as published by
  * the Free Software Foundation; either version 2 of the License, or
  * (at your option) any later version
  *
- * Kamailio is distributed in the hope that it will be useful,
+ * SIP-router is distributed in the hope that it will be useful,
  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  * GNU General Public License for more details.
@@ -26,6 +26,14 @@
  *  2003-04-07 first version.  
  */
 
+/*!
+ * \file
+ * \brief SIP-utils :: Mangler
+ * \ingroup siputils
+ * - Module; \ref siputils
+ */
+
+
 #ifndef UTILS_H
 #define UTILS_H
 

modules_k/sqlops/README

@@ -12,30 +12,30 @@ Daniel-Constantin Mierla
    <[email protected]>
 
    Copyright © 2008 http://www.asipto.com
-     __________________________________________________________
+     __________________________________________________________________
 
    Table of Contents
 
    1. Admin Guide
 
-        1.1. Overview
-        1.2. Dependencies
+        1. Overview
+        2. Dependencies
 
-              1.2.1. Kamailio Modules
-              1.2.2. External Libraries or Applications
+              2.1. Kamailio Modules
+              2.2. External Libraries or Applications
 
-        1.3. Exported Parameters
+        3. Exported Parameters
 
-              1.3.1. sqlcon (str)
+              3.1. sqlcon (str)
 
-        1.4. Exported Functions
+        4. Exported Functions
 
-              1.4.1. sql_query(connection, query, result)
-              1.4.2. sql_result_free(result)
+              4.1. sql_query(connection, query, result)
+              4.2. sql_result_free(result)
 
-        1.5. Exported pseudo-variables
+        5. Exported pseudo-variables
 
-              1.5.1. $dbr(result=>key)
+              5.1. $dbr(result=>key)
 
    List of Examples
 
@@ -46,90 +46,118 @@ Daniel-Constantin Mierla
 
 Chapter 1. Admin Guide
 
-1.1. Overview
-
-   The module adds support for raw SQL queries in configuration
-   file.
-
-   Among features:
-     * many DB connections - the module can connect to many
-       databases on different servers using different DB driver
-       modules at the same time.
-     * many DB results - the module can store many results of
-       different SQL queries in separate structures at the same
-       time. Thus is possible to work in parallel with several DB
-       results.
-     * access via pseudo-variables - the content of SQL query
-       result is accessible via pseudo-variables. Please note that
-       only integer and string variables are supported at the
-       moment because of the internal usage of "AVPs" to hold the
-       values. So its not possible for example to return floating
-       point or big integer values this way.
-     * array indexes - fast access to result values via array
-       possition: [row,column].
-     * persistence in process space - a result can be used many
-       times in same worker process. Query once, use many times.
-
-1.2. Dependencies
-
-1.2.1. Kamailio Modules
+   Table of Contents
+
+   1. Overview
+   2. Dependencies
+
+        2.1. Kamailio Modules
+        2.2. External Libraries or Applications
+
+   3. Exported Parameters
+
+        3.1. sqlcon (str)
+
+   4. Exported Functions
+
+        4.1. sql_query(connection, query, result)
+        4.2. sql_result_free(result)
+
+   5. Exported pseudo-variables
+
+        5.1. $dbr(result=>key)
+
+1. Overview
+
+   The module adds support for raw SQL queries in the configuration file.
+
+   Among the features:
+     * Multiple DB connections - the module can connect to many databases
+       on different servers using different DB driver modules at the same
+       time.
+     * many DB results - the module can store many results of different
+       SQL queries in separate structures at the same time. Thus it is
+       possible to work in parallel with several DB results.
+     * access via pseudo-variables - the content of the SQL query result
+       is accessible via pseudo-variables. Please note that only integer
+       and string variables are supported at the moment because of the
+       internal usage of "AVPs" to hold the values. So its not possible
+       for example to return floating point or big integer values this
+       way.
+     * array indexes - fast access to result values via array position:
+       [row,column].
+     * persistence in process space - a result can be used many times in
+       the same worker process. Query once, use many times.
+
+2. Dependencies
+
+   2.1. Kamailio Modules
+   2.2. External Libraries or Applications
+
+2.1. Kamailio Modules
 
    The following modules must be loaded before this module:
      * a DB SQL module (mysql, postgres, ...).
 
-1.2.2. External Libraries or Applications
+2.2. External Libraries or Applications
 
-   The following libraries or applications must be installed
-   before running Kamailio with this module loaded:
+   The following libraries or applications must be installed before
+   running Kamailio with this module loaded:
      * None.
 
-1.3. Exported Parameters
+3. Exported Parameters
+
+   3.1. sqlcon (str)
 
-1.3.1. sqlcon (str)
+3.1. sqlcon (str)
 
-   The definition of DB connection. The value of the parameter
-   must have the following format:
+   The definition of a DB connection. The value of the parameter must have
+   the following format:
      * "connection_name=>database_url"
 
-   The parameter can be set multiple times to get many DB
-   connections in same configuration file.
-     * connection_name - string specifying the name of DB
-       connection. This string is used by sql_query() function to
-       refer to the DB connection.
-     * database_url - URL to connect to database.
+   This parameter may be set multiple times to get many DB connections in
+   the same configuration file.
+     * connection_name - string specifying the name of a DB connection.
+       This string is used by the "sql_query()" function to refer to the
+       DB connection.
+     * database_url - Standardized database URL used to connect to
+       database.
 
    Default value is NULL.
 
    Example 1.1. Set sqlcon parameter
 ...
 modparam("sqlops","sqlcon","cb=>mysql://openser:[email protected]/testdb")
-modparam("sqlops","sqlcon","ca=>mysql://openser:abc@localhost/openser")
+modparam("sqlops","sqlcon","ca=>dbdriver://username:password@dbhost/dbname")
 ...
 
-1.4. Exported Functions
+4. Exported Functions
 
-1.4.1.  sql_query(connection, query, result)
+   4.1. sql_query(connection, query, result)
+   4.2. sql_result_free(result)
+
+4.1. sql_query(connection, query, result)
 
    Make a SQL query using 'connection' and store data in 'result'.
-     * connection - the name of the connection to be used for
-       query (defined via sqlcon parameter).
-     * query - SQL query string, can contain pseudo-variables.
-     * result - string name to identify the result. Will be used
-       by $dbr(...) pseudo-variable to access result attributes.
+     * connection - the name of the connection to be used for query
+       (defined via the "sqlcon" parameter).
+     * query - SQL query string or pseudo-variables containing SQL query.
+     * result - string name to identify the result. Will be used by
+       $dbr(...) pseudo-variable to access result attributes.
 
    This function can be used from REQUEST_ROUTE, FAILURE_ROUTE,
    ONREPLY_ROUTE, BRANCH_ROUTE.
 
    Example 1.2. sql_query() usage
 ...
-modparam("sqlops","sqlcon","ca=>mysql://openser:abc@localhost/openser")
+modparam("sqlops","sqlcon","ca=>dbdriver://username:password@dbhost/dbname")
 ...
 sql_query("ca", "select * from domain", "ra");
 xlog("number of rows in table domain: $dbr(ra=>rows)\n");
 sql_result_free("ra");
 ...
 
-1.4.2.  sql_result_free(result)
+4.2. sql_result_free(result)
 
    Free data in SQL 'result'.
 
@@ -138,7 +166,7 @@ sql_result_free("ra");
 
    Example 1.3. sql_result_free() usage
 ...
-modparam("sqlops","sqlcon","ca=>mysql://openser:abc@localhost/openser")
+modparam("sqlops","sqlcon","ca=>dbdriver://username:password@dbhost/dbname")
 ...
 sql_query("ca", "select * from domain", "ra");
 xlog("number of rows in table domain: $dbr(ra=>rows)\n");
@@ -146,26 +174,28 @@ xlog("number of rows in table domain: $dbr(ra=>rows)\n");
 sql_result_free("ra");
 ...
 
-1.5. Exported pseudo-variables
+5. Exported pseudo-variables
+
+   5.1. $dbr(result=>key)
 
-1.5.1. $dbr(result=>key)
+5.1. $dbr(result=>key)
 
    Access hash table entries.
 
-   The "result" must be the name identifying a SQL result (third
-   parameter of sql_query(...)).
+   The "result" must be the name identifying a SQL result (third parameter
+   of sql_query(...)).
 
    The "key" can be:
-     * rows - return number of rows in result
-     * cols - return the number of columns in result.
-     * [row,col] - return the value at position (row,col) in
-       result. 'row' and 'col' must be integer or pseudo-variable
-       holding an integer.
-     * colname[N] - return the name of the N-th column in result.
+     * rows - return the number of rows in query result
+     * cols - return the number of columns in the result.
+     * [row,col] - return the value at position (row,col) in the result
+       set. 'row' and 'col' must be integer or pseudo-variable holding an
+       integer.
+     * colname[N] - return the name of the N-th column in the result set.
 
    Example 1.4. $dbr(result=>key) usage
 ...
-modparam("sqlops","sqlcon","ca=>mysql://openser:abc@localhost/openser")
+modparam("sqlops","sqlcon","ca=>dbdriver://username:password@dbhost/dbname")
 ...
 sql_query("ca", "select * from domain", "ra");
 xlog("rows: $dbr(ra=>rows) cols: $dbr(ra=>cols)\n");
@@ -174,8 +204,7 @@ if($dbr(ra=>rows)>0)
     $var(i) = 0;
     while($var(i)<$dbr(ra=>cols))
     {
-        xlog("--- SCRIPT: column[$var(i)] = $dbr(ra=>colname[$var(i)])\n
-");
+        xlog("--- SCRIPT: column[$var(i)] = $dbr(ra=>colname[$var(i)])\n");
         $var(i) = $var(i) + 1;
     }
     $var(i) = 0;

modules_k/sqlops/doc/sqlops_admin.xml

@@ -16,15 +16,15 @@
 	<section>
 	<title>Overview</title>
 	<para>
-		The module adds support for raw SQL queries in configuration file.
+		The module adds support for raw SQL queries in the configuration file.
 	</para>
 	<para>
-		Among features:
+		Among the features:
 	</para>
 	<itemizedlist>
 		<listitem>
 		<para>
-			<emphasis>many DB connections</emphasis> - the module can connect
+			<emphasis>Multiple DB connections</emphasis> - the module can connect
 			to many databases on different servers using different DB
 			driver modules at the same time.
 		</para>
@@ -33,14 +33,14 @@
 		<para>
 			<emphasis>many DB results</emphasis> - the module can store
 			many results of different SQL queries in separate structures at
-			the same time. Thus is possible to work in parallel with several
+			the same time. Thus it is possible to work in parallel with several
 			DB results.
 		</para>
 		</listitem>
 		<listitem>
 		<para>
 			<emphasis>access via pseudo-variables</emphasis> - the content
-			of SQL query result is accessible via pseudo-variables. Please
+			of the SQL query result is accessible via pseudo-variables. Please
 			note that only integer and string variables are supported at the
 			moment because of the internal usage of <quote>AVPs</quote> to hold
 			the values. So its not possible for example to return floating point
@@ -50,13 +50,13 @@
 		<listitem>
 		<para>
 			<emphasis>array indexes</emphasis> - fast access to result values
-			via array possition: [row,column].
+			via array position: [row,column].
 		</para>
 		</listitem>
 		<listitem>
 		<para>
 			<emphasis>persistence in process space</emphasis> - a result can
-			be used many times in same worker process. Query once, use many
+			be used many times in the same worker process. Query once, use many
 			times.
 		</para>
 		</listitem>
@@ -100,7 +100,7 @@
 	<section>
 		<title><varname>sqlcon</varname> (str)</title>
 		<para>
-		The definition of DB connection. The value of the parameter must have
+		The definition of a DB connection. The value of the parameter must have
 		the following format:
 		</para>
 		<itemizedlist>
@@ -111,20 +111,20 @@
 		</listitem>
 		</itemizedlist>
 		<para>
-			The parameter can be set multiple times to get many DB connections
-			in same configuration file.
+			This parameter may be set multiple times to get many DB connections
+			in the same configuration file.
 		</para>
 		<itemizedlist>
 		<listitem>
 		<para>
 			<emphasis>connection_name</emphasis> - string specifying the name
-			of DB connection. This string is used by sql_query() function to
+			of a DB connection. This string is used by the <quote>sql_query()</quote> function to
 			refer to the DB connection.
 		</para>
 		</listitem>
 		<listitem>
 		<para>
-			<emphasis>database_url</emphasis> - URL to connect to database.
+			<emphasis>database_url</emphasis> - Standardized database URL used to connect to database.
 		</para>
 		</listitem>
 		</itemizedlist>
@@ -138,7 +138,7 @@
 		<programlisting format="linespecific">
 ...
 modparam("sqlops","sqlcon","cb=&gt;mysql://openser:[email protected]/testdb")
-modparam("sqlops","sqlcon","ca=&gt;mysql://openser:abc@localhost/openser")
+modparam("sqlops","sqlcon","ca=&gt;&exampledb;")
 ...
 </programlisting>
 		</example>
@@ -157,13 +157,12 @@ modparam("sqlops","sqlcon","ca=&gt;mysql://openser:abc@localhost/openser")
 		<listitem>
 			<para>
 				<emphasis>connection</emphasis> - the name of the connection
-				to be used for query (defined via sqlcon parameter).
+				to be used for query (defined via the <quote>sqlcon</quote> parameter).
 			</para>
 		</listitem>
 		<listitem>
 			<para>
-				<emphasis>query</emphasis> - SQL query string, can contain
-				pseudo-variables.
+				<emphasis>query</emphasis> - SQL query string or pseudo-variables containing SQL query.
 			</para>
 		</listitem>
 		<listitem>
@@ -182,7 +181,7 @@ modparam("sqlops","sqlcon","ca=&gt;mysql://openser:abc@localhost/openser")
 		<title><function>sql_query()</function> usage</title>
 		<programlisting format="linespecific">
 ...
-modparam("sqlops","sqlcon","ca=&gt;mysql://openser:abc@localhost/openser")
+modparam("sqlops","sqlcon","ca=&gt;&exampledb;")
 ...
 sql_query("ca", "select * from domain", "ra");
 xlog("number of rows in table domain: $dbr(ra=&gt;rows)\n");
@@ -206,7 +205,7 @@ sql_result_free("ra");
 		<title><function>sql_result_free()</function> usage</title>
 		<programlisting format="linespecific">
 ...
-modparam("sqlops","sqlcon","ca=&gt;mysql://openser:abc@localhost/openser")
+modparam("sqlops","sqlcon","ca=&gt;&exampledb;")
 ...
 sql_query("ca", "select * from domain", "ra");
 xlog("number of rows in table domain: $dbr(ra=&gt;rows)\n");
@@ -236,21 +235,21 @@ sql_result_free("ra");
 			</para>
 			<itemizedlist>
 				<listitem>
-					<para><emphasis>rows</emphasis> - return number of rows in
-						result</para>
+					<para><emphasis>rows</emphasis> - return the number of rows in
+						query result</para>
 				</listitem>	  
 				<listitem>
 					<para><emphasis>cols</emphasis> - return the number of
-						columns in result.</para>
+						columns in the result.</para>
 				</listitem>	  
 				<listitem>
 					<para><emphasis>[row,col]</emphasis> - return the value
-						at position (row,col) in result. 'row' and 'col' must
+						at position (row,col) in the result set. 'row' and 'col' must
 					be integer or pseudo-variable holding an integer.</para>
 				</listitem>
 				<listitem>
 					<para><emphasis>colname[N]</emphasis> - return the name
-						of the N-th column in result.</para>
+						of the N-th column in the result set.</para>
 				</listitem>	  
 			</itemizedlist>
 
@@ -258,7 +257,7 @@ sql_result_free("ra");
 				<title><function moreinfo="none">$dbr(result=&gt;key)</function> usage</title>
 				<programlisting format="linespecific">
 ...
-modparam("sqlops","sqlcon","ca=&gt;mysql://openser:abc@localhost/openser")
+modparam("sqlops","sqlcon","ca=&gt;&exampledb;")
 ...
 sql_query("ca", "select * from domain", "ra");
 xlog("rows: $dbr(ra=&gt;rows) cols: $dbr(ra=&gt;cols)\n");

modules_k/sqlops/sql_api.c

@@ -20,6 +20,14 @@
  * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
  */
 
+/*! \file
+ * \ingroup sqlops
+ * \brief SIP-router SQL-operations :: API
+ *
+ * - Module: \ref sqlops
+ */
+
+
 #include "../../mem/mem.h"
 #include "../../dprint.h"
 #include "../../lib/kcore/hash_func.h"

modules_k/sqlops/sql_api.h

@@ -19,6 +19,14 @@
  * along with this program; if not, write to the Free Software
  * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
  */
+
+/*! \file
+ * \ingroup sqlops
+ * \brief SIP-router SQL-operations :: API
+ *
+ * - Module: \ref sqlops
+ */
+
 		       
 #ifndef _SQL_API_H_
 #define _SQL_API_H_

modules_k/sqlops/sql_var.c

@@ -20,6 +20,14 @@
  * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
  */
 
+/*! \file
+ * \ingroup sqlops
+ * \brief SIP-router SQL-operations :: Variables
+ *
+ * - Module: \ref sqlops
+ */
+
+
 #include "../../mem/mem.h"
 #include "../../dprint.h"
 #include "../../mod_fix.h"

modules_k/sqlops/sql_var.h

@@ -19,6 +19,14 @@
  * along with this program; if not, write to the Free Software
  * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
  */
+
+/*! \file
+ * \ingroup sqlops
+ * \brief SIP-router SQL-operations :: Variables
+ *
+ * - Module: \ref sqlops
+ */
+
 		       
 #ifndef _SQL_VAR_H_
 #define _SQL_VAR_H_

modules_k/sqlops/sqlops.c

@@ -20,6 +20,24 @@
  * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
  */
 
+/*! \file
+ * \ingroup sqlops
+ * \brief SIP-router SQL-operations :: Module interface
+ *
+ * - Module: \ref sqlops
+ */
+
+/*! \defgroup sqlops SIP-Router :: SQL Operations
+ *  \note Kamailio module - part of modules_k
+
+ * The module adds support for raw SQL queries in the configuration file.
+
+ */
+
+
+
+
+
 #include <stdio.h>
 #include <string.h>
 #include <stdlib.h>