pi_http Module
     __________________________________________________________

   Table of Contents

   1. Admin Guide

        1.1. Overview
        1.2. Usage
        1.3. Framework

              1.3.1. Database connection definition block
              1.3.2. Table definition block
              1.3.3. Command definition block

        1.4. To-do
        1.5. Dependencies

              1.5.1. OpenSIPS Modules

        1.6. External Libraries or Applications
        1.7. Exported Parameters

              1.7.1. pi_http_root(string)
              1.7.2. framework(string)
              1.7.3. pi_http_method(integrer)

        1.8. Exported MI Functions

              1.8.1. pi_reload_tbls_and_cmds

   2. Contributors

        2.1. By Commit Statistics
        2.2. By Commit Activity

   3. Documentation

        3.1. Contributors

   List of Tables

   2.1. Top contributors by DevScore^(1), authored commits^(2) and
          lines added/removed^(3)

   2.2. Most recently active contributors^(1) to this module

   List of Examples

   1.1. Set pi_http_root parameter
   1.2. Set framework parameter
   1.3. Set pi_http_method parameter

Chapter 1. Admin Guide

1.1. Overview

   This module provides an HTTP provisioning interface for
   OpenSIPS. It is using the OpenSIPS's internal database API to
   provide a simple way of manipulating records inside OpenSIPS's
   tables.

   The module offers:
     * ability to connect to multiple/different databases through
       OpenSIPS's db API; (all OpenSIPS's databases are
       supported);
     * ability to perform data input validation through OpenSIPS
       API;
     * ability to reconfigure the interface layout on the fly by
       reloading the config from the xml framework via mi command
       interface.

   Note: when provisioning tables using db_text, any change made
   to a db_text table will not be reflected on the actual text
   file. In order to force a write out to the disk of the cached
   tables, the db_text mi command dbt_dump must be used.

1.2. Usage

   The layout of the provisioning interface is controlled via an
   external xml file (see the framework parameter). An example of
   a framework xml file is provided inside the examples directory
   of the pi_http module. A simple framework file can be generated
   by the opensips-cli command:
opensips-cli pframework create

   The generated framework will be saved inside OpenSIPS's config
   directory as pi_framework_sample. The list of configurable
   tables will be based on the "database_modules" setting of
   opensips-cli.cfg if present, otherwise a default set of
   configurable tables will be used.

1.3. Framework

   The xml framework file is organized in three distinctive
   blocks:
     * database connection definition block
     * table definition block
     * command definition block

1.3.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 OpenSIPS
   modules that are using a database.

   Supported databases:
     * berkeley
     * flatstore
     * http
     * mysql
     * oracle
     * postgres
     * text
     * unixodbc
     * virtual

1.3.2. Table definition block

   Each table managed through the OpenSIPS 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 OpenSIPS
   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:
     * DB_INT
     * DB_BIGINT
     * DB_DOUBLE
     * DB_STRING
     * DB_STR
     * DB_DATETIME
          + Note: input field must be provided in 'YEAR-MM-DD
            HH:MM:SS' format.
     * DB_BLOB
     * DB_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]

1.3.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:
     * DB_QUERY - performs an SQL query and supports three type of
       columns:
          + clause: 0 or more columns
          + query: 1 column
          + order: 0 or 1 column
     * DB_INSERT - performs an SQL insert and supports one type of
       column:
          + query: 1 or more columns
     * DB_DELETE - performs an SQL delete and supports one type of
       column:
          + clause: 1 or more columns
     * DB_UPDATE - performs an SQL update and supports two type of
       columns:
          + clause: 0 or more columns
          + query: 1 or more columns
     * DB_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.

1.4. To-do

   Features to be added in the future:
     * full subscriber provisionning with automatic ha1/ha1b
       fields.

1.5. Dependencies

1.5.1. OpenSIPS Modules

   The following modules must be loaded before this module:
     * httpd module.

1.6. External Libraries or Applications

   The following libraries or applications must be installed
   before running OpenSIPS with this module loaded:
     * libxml2

1.7. Exported Parameters

1.7.1. pi_http_root(string)

   Specifies the root path for pi HTTP requests. The link to the
   OpenSIPS provisioning web interface must be constructed using
   the following patern:
   http://[opensips_IP]:[opensips_mi_port]/[pi_http_root]

   The default value is "pi".

   Example 1.1. Set pi_http_root parameter
...
modparam("pi_http", "pi_http_root", "opensips_pi")
...

1.7.2. framework(string)

   Specifies the full path for xml framework descriptor.

   There's no default value. This parameter is mandatory.

   Example 1.2. Set framework parameter
...
modparam("pi_http", "framework", "/usr/local/etc/opensips/pi_framework.x
ml")
...

1.7.3. pi_http_method(integrer)

   Specifies the HTTP request method to be used:
     * 0 - use GET HTTP request
     * 1 - use POST HTTP request

   The default value is 0.

   Example 1.3. Set pi_http_method parameter
...
modparam("pi_http", "pi_http_method", 1)
...

1.8. Exported MI Functions

1.8.1. pi_reload_tbls_and_cmds

   Reloads the layout of the provisioning interface from the
   framework file.

   Name: pi_reload_tbls_and_cmds

   Parameters: none

   MI FIFO Command Format:
opensips-cli -x mi pi_reload_tbls_and_cmds

Chapter 2. Contributors

2.1. By Commit Statistics

   Table 2.1. Top contributors by DevScore^(1), authored
   commits^(2) and lines added/removed^(3)
     Name DevScore Commits Lines ++ Lines --
   1. Ovidiu Sas (@ovidiusas) 72 31 4389 206
   2. Liviu Chircu (@liviuchircu) 15 13 40 57
   3. Razvan Crainea (@razvancrainea) 13 11 30 31
   4. Bogdan-Andrei Iancu (@bogdan-iancu) 7 5 5 5
   5. Vlad Patrascu (@rvlad-patrascu) 6 4 21 19
   6. Maksym Sobolyev (@sobomax) 5 3 8 5
   7. Ionut Ionita (@ionutrazvanionita) 4 2 53 28
   8. Vlad Paiu (@vladpaiu) 4 2 5 2
   9. Zero King (@l2dy) 3 1 2 2
   10. Peter Lemenkov (@lemenkov) 3 1 1 1

   (1) DevScore = author_commits + author_lines_added /
   (project_lines_added / project_commits) + author_lines_deleted
   / (project_lines_deleted / project_commits)

   (2) including any documentation-related commits, excluding
   merge commits. Regarding imported patches/code, we do our best
   to count the work on behalf of the proper owner, as per the
   "fix_authors" and "mod_renames" arrays in
   opensips/doc/build-contrib.sh. If you identify any
   patches/commits which do not get properly attributed to you,
   please submit a pull request which extends "fix_authors" and/or
   "mod_renames".

   (3) ignoring whitespace edits, renamed files and auto-generated
   files

2.2. By Commit Activity

   Table 2.2. Most recently active contributors^(1) to this module
                      Name                   Commit Activity
   1.  Liviu Chircu (@liviuchircu)         Mar 2014 - Mar 2024
   2.  Maksym Sobolyev (@sobomax)          Oct 2022 - Feb 2023
   3.  Bogdan-Andrei Iancu (@bogdan-iancu) Jan 2013 - Mar 2020
   4.  Zero King (@l2dy)                   Mar 2020 - Mar 2020
   5.  Razvan Crainea (@razvancrainea)     Aug 2015 - Sep 2019
   6.  Vlad Patrascu (@rvlad-patrascu)     May 2017 - Jan 2019
   7.  Peter Lemenkov (@lemenkov)          Jun 2018 - Jun 2018
   8.  Ionut Ionita (@ionutrazvanionita)   Nov 2015 - Jan 2017
   9.  Ovidiu Sas (@ovidiusas)             Oct 2012 - Apr 2016
   10. Vlad Paiu (@vladpaiu)               May 2013 - May 2013

   (1) including any documentation-related commits, excluding
   merge commits

Chapter 3. Documentation

3.1. Contributors

   Last edited by: Liviu Chircu (@liviuchircu), Razvan Crainea
   (@razvancrainea), Peter Lemenkov (@lemenkov), Vlad Patrascu
   (@rvlad-patrascu), Ovidiu Sas (@ovidiusas), Bogdan-Andrei Iancu
   (@bogdan-iancu).

   Documentation Copyrights:

   Copyright © 2012-2013 VoIP Embedded, Inc.
