[sr-dev] git:master: xhttp_pi: add missing README

Module: sip-router Branch: master Commit: 63b5065ccf776ce3bbc5b51f19f72041442467cb URL: http://git.sip-router.org/cgi-bin/gitweb.cgi/sip-router/?a=commit;h=63b5065… Author: Henning Westerholt &lt;hw(a)kamailio.org&gt; Committer: Henning Westerholt &lt;hw(a)kamailio.org&gt; 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 + + &lt;osas(a)voipembedded.com&gt; + +Edited by + +Ovidiu Sas + + &lt;osas(a)voipembedded.com&gt; + + 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