[sr-dev] git:master: xhttp_pi: add missing README
Henning Westerholt
hw at kamailio.org
Thu Dec 13 17:48:12 CET 2012
Module: sip-router
Branch: master
Commit: 63b5065ccf776ce3bbc5b51f19f72041442467cb
URL: http://git.sip-router.org/cgi-bin/gitweb.cgi/sip-router/?a=commit;h=63b5065ccf776ce3bbc5b51f19f72041442467cb
Author: Henning Westerholt <hw at kamailio.org>
Committer: Henning Westerholt <hw at kamailio.org>
Date: Thu Dec 13 17:47:57 2012 +0100
xhttp_pi: add missing README
---
modules/xhttp_pi/README | 306 +++++++++++++++++++++++++++++++++++++++++++++++
1 files changed, 306 insertions(+), 0 deletions(-)
diff --git a/modules/xhttp_pi/README b/modules/xhttp_pi/README
new file mode 100644
index 0000000..4840bce
--- /dev/null
+++ b/modules/xhttp_pi/README
@@ -0,0 +1,306 @@
+xHTTP_PI Module
+
+Ovidiu Sas
+
+ <osas at voipembedded.com>
+
+Edited by
+
+Ovidiu Sas
+
+ <osas at voipembedded.com>
+
+ 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
More information about the sr-dev
mailing list