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

[Ovidiu Sas]

Thank you.  I was under the impression that was already in :)

-ovidiu

On Thu, Dec 13, 2012 at 11:48 AM, Henning Westerholt <hw at kamailio.org> wrote:
> 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
>