xhttp_pi: add missing README

modules/xhttp_pi/README

@@ -0,0 +1,306 @@
+xHTTP_PI Module
+
+Ovidiu Sas
+
+   <[email protected]>
+
+Edited by
+
+Ovidiu Sas
+
+   <[email protected]>
+
+   Copyright © 2012 VoIPEmbedded Inc.
+     __________________________________________________________________
+
+   Table of Contents
+
+   1. Admin Guide
+
+        1. Overview
+        2. Usage
+
+              2.1. Database connection definition block
+              2.2. Table definition block
+              2.3. Command definition block
+
+        3. To-do
+        4. Dependencies
+
+              4.1. Kamailio Modules
+              4.2. External Libraries or Applications
+
+        5. Parameters
+
+              5.1. xhttp_pi_root (str)
+              5.2. xhttp_pi_buf_size (int)
+              5.3. framework (string)
+
+        6. Functions
+
+              6.1. dispatch_xhttp_pi()
+
+        7. Exported RPC Functions
+
+              7.1. xhttp_pi.reload
+
+   List of Examples
+
+   1.1. Set xhttp_pi_root parameter
+   1.2. Set xhttp_pi_buf_size parameter
+   1.3. Set framework parameter
+   1.4. dispatch_xhttp_pi usage
+
+Chapter 1. Admin Guide
+
+   Table of Contents
+
+   1. Overview
+   2. Usage
+
+        2.1. Database connection definition block
+        2.2. Table definition block
+        2.3. Command definition block
+
+   3. To-do
+   4. Dependencies
+
+        4.1. Kamailio Modules
+        4.2. External Libraries or Applications
+
+   5. Parameters
+
+        5.1. xhttp_pi_root (str)
+        5.2. xhttp_pi_buf_size (int)
+        5.3. framework (string)
+
+   6. Functions
+
+        6.1. dispatch_xhttp_pi()
+
+   7. Exported RPC Functions
+
+        7.1. xhttp_pi.reload
+
+1. Overview
+
+   This module provides a web provisioning interface for Kamailio. It is
+   using the Kamailio's internal database API to provide a simple way of
+   manipulating records inside Kamailio's tables.
+
+   The module offers:
+     * ability to connect to multiple/different databases through
+       Kamailio's db API; (all Kamailio's databases are supported);
+     * ability to perform data input validation through Kamailio API;
+     * ability to reconfigure the interface layout on the fly by reloading
+       the config from the xml framework via the rpc command interface.
+
+2. Usage
+
+   2.1. Database connection definition block
+   2.2. Table definition block
+   2.3. Command definition block
+
+   The layout of the provisionning interface is controlled via an external
+   xml file (see the framework parameter). An example of a framework xml
+   file is provided inside the Kamailio's examples directory. The xml
+   framework file is organized in three distinctive blocks:
+     * database connection definition block
+     * table definition block
+     * command definition block
+
+2.1. Database connection definition block
+
+   Each connection to a particular database must be defined here with a
+   unique database connection id. The connection parameters are defined
+   following the db_url param pattern for all Kamailio modules that are
+   using a database.
+
+   Supported databases:
+     * berkeley
+     * cassandra
+     * cluster
+     * flatstore
+     * mysql
+     * oracle
+     * postgres
+     * sqlite
+     * text
+     * unixodbc
+
+2.2. Table definition block
+
+   Each table managed through the Kamailio provisioning interface must be
+   defined here with a unique table id. For each table, the database
+   connection id must be specified. Each table must list all columns that
+   will be managed by the Kamailio provisioning interface. Each column
+   must have a unique field name and a type. Each column may have a
+   validation tag for validating input data.
+
+   Supported column types:
+     * DB1_INT
+     * DB1_BIGINT
+     * DB1_DOUBLE
+     * DB1_STRING
+     * DB1_STR
+     * DB1_DATETIME
+     * DB1_BLOB
+     * DB1_BITMAP
+
+   Supported validation methods:
+     * IPV4 - represents an IPv4 address
+     * URI - represents a SIP URI
+     * URI_IPV4HOST - represents a SIP URI with an IPV4 as a host
+     * P_HOST_PORT - represents [proto:]host[:port]
+     * P_IPV4_PORT - represents [proto:]IPv4[:port]
+
+2.3. Command definition block
+
+   Multiple provisioning commands can be grouped together. Each group can
+   have multiple commands. Each command definition in a group must have
+   the table id of the table that is operating on along with the command
+   type to be performed.
+
+   The command type can have up to three type of column parameters:
+     * clause columns
+     * query columns
+     * order by columns
+
+   Each column parameter must define the name(s) of the column(s) (must
+   match a field name in the description table identified by the table
+   id). A column can accept a list of imposed values. Each imposed value
+   will have an id that will be displayed on the web interface and the
+   actual value that will be used for db operations. Clause columns must
+   define operators. Here's the list of supported operators: '<', '>',
+   '=', '<=', '>=', '!='.
+
+   Supported database command types:
+     * DB1_QUERY - performs an SQL query and supports three type of
+       columns:
+          + clause: 0 or more columns
+          + query: 1 column
+          + order: 0 or 1 column
+     * DB1_INSERT - performs an SQL insert and supports one type of
+       column:
+          + query: 1 or more columns
+     * DB1_DELETE - performs an SQL delete and supports one type of
+       column:
+          + clause: 1 or more columns
+     * DB1_UPDATE - performs an SQL update and supports two type of
+       columns:
+          + clause: 0 or more columns
+          + query: 1 or more columns
+     * DB1_REPLACE - performs an SQL replace and supports one type of
+       column:
+          + query: 1 or more columns
+
+   Please note that some databases have a restricted set of database
+   command types.
+
+3. To-do
+
+   Features to be added in the future:
+     * full subscriber provisionning with automatic ha1/ha1b fields;
+     * accept empty values as NULL;
+
+4. Dependencies
+
+   4.1. Kamailio Modules
+   4.2. External Libraries or Applications
+
+4.1. Kamailio Modules
+
+   The following modules must be loaded before this module:
+     * xhttp - xHTTP.
+
+4.2. External Libraries or Applications
+
+   The following libraries or applications must be installed before
+   running Kamailio with this module loaded:
+     * libxml2
+
+5. Parameters
+
+   5.1. xhttp_pi_root (str)
+   5.2. xhttp_pi_buf_size (int)
+   5.3. framework (string)
+
+5.1. xhttp_pi_root (str)
+
+   It specifies the root path for provisionning http requests. The link to
+   the provisioning web interface must be constructed using the following
+   patern: http://[server_IP]:[tcp_port]/[xhttp_pi_root]
+
+   Default value is "rpc".
+
+   Example 1.1. Set xhttp_pi_root parameter
+...
+modparam("xhttp_rpc", "xhttp_pi_root", "pi")
+...
+
+5.2. xhttp_pi_buf_size (int)
+
+   It specifies the maximum length of the buffer used to write in the HTML
+   reply information in order to build the HTML response.
+
+   Default value is 0 (auto set to 1/3 of the size of the configured pkg
+   mem).
+
+   Example 1.2. Set xhttp_pi_buf_size parameter
+...
+modparam("xhttp", "xhttp_pi_buf_size", 1024)
+...
+
+5.3. framework (string)
+
+   It specifies the full path for xml framework descriptor.
+
+   There's no default value. This parameter is mandatory.
+
+   Example 1.3. Set framework parameter
+...
+modparam("xhttp", "framework", "/usr/local/etc/kamailio/pi_framework.xml")
+...
+
+6. Functions
+
+   6.1. dispatch_xhttp_pi()
+
+6.1.  dispatch_xhttp_pi()
+
+   Handle the HTTP request and generate a response.
+
+   Example 1.4. dispatch_xhttp_pi usage
+...
+tcp_accept_no_cl=yes
+...
+loadmodule "sl.so"
+loadmodule "xhttp.so"
+loadmodule "xhttp_rpc.so"
+...
+modparam("xhttp_rpc", "xhttp_pi_root", "pi")
+...
+event_route[xhttp:request] {
+        $var(xhttp_rpc_root) = $(hu{s.substr,0,3});
+        if ($var(xhttp_rpc_root) == "/pi")
+                dispatch_xhttp_pi();
+        else
+                xhttp_reply("200", "OK", "text/html",
+                                "<html><body>Wrong URL $hu</body></html>");
+}
+...
+
+7. Exported RPC Functions
+
+   7.1. xhttp_pi.reload
+
+7.1.  xhttp_pi.reload
+
+   Reloads the xml framework.
+
+   Name: xhttp_pi.reload
+
+   Parameters: none
+
+   RPC Command Format:
+                kamctl xhttp_pi.reload