modules: readme files regenerated - cplc ...
authorKamailio Dev <kamailio.dev@kamailio.org>
Tue, 3 Jan 2017 11:01:14 +0000 (12:01 +0100)
committerKamailio Dev <kamailio.dev@kamailio.org>
Tue, 3 Jan 2017 11:01:14 +0000 (12:01 +0100)
src/modules/cplc/README

index 139597f..45732f2 100644 (file)
@@ -1,2 +1,568 @@
+cplc Module
 
+Bogdan-Andrei Iancu
 
+   Voice Sistem SRL
+
+Edited by
+
+Bogdan-Andrei Iancu
+
+   Copyright © 2003 FhG FOKUS
+     __________________________________________________________________
+
+   Table of Contents
+
+   1. Admin Guide
+
+        1. Overview
+        2. Dependencies
+
+              2.1. Kamailio Modules
+              2.2. External Libraries or Applications
+
+        3. Parameters
+
+              3.1. db_url (string)
+              3.2. db_table (string)
+              3.3. username_column (string)
+              3.4. domain_column (string)
+              3.5. cpl_xml_column (string)
+              3.6. cpl_bin_column (string)
+              3.7. cpl_dtd_file (string)
+              3.8. log_dir (string)
+              3.9. proxy_recurse (int)
+              3.10. proxy_route (int)
+              3.11. case_sensitive (int)
+              3.12. realm_prefix (string)
+              3.13. timer_avp (string)
+              3.14. lookup_domain (string)
+              3.15. lookup_append_branches (int)
+              3.16. use_domain (integer)
+
+        4. Functions
+
+              4.1. cpl_run_script(type,mode, [uri])
+              4.2. cpl_process_register()
+              4.3. cpl_process_register_norpl()
+
+        5. RPC Commands
+
+              5.1. cpl.load
+              5.2. cpl.remove
+              5.3. cpl.get
+
+        6. Installation and Running
+
+              6.1. Database setup
+
+   List of Examples
+
+   1.1. Set db_url parameter
+   1.2. Set db_table parameter
+   1.3. Set username_column parameter
+   1.4. Set domain_column parameter
+   1.5. Set cpl_xml_column parameter
+   1.6. Set cpl_bin_column parameter
+   1.7. Set cpl_dtd_file parameter
+   1.8. Set log_dir parameter
+   1.9. Set proxy_recurse parameter
+   1.10. Set proxy_route parameter
+   1.11. Set case_sensitive parameter
+   1.12. Set realm_prefix parameter
+   1.13. Set timer_avp parameter
+   1.14. Set lookup_domain parameter
+   1.15. Set lookup_append_branches parameter
+   1.16. Set use_domain parameter
+   1.17. cpl_run_script usage
+   1.18. cpl_process_register usage
+   1.19. cpl_process_register_norpl usage
+
+Chapter 1. Admin Guide
+
+   Table of Contents
+
+   1. Overview
+   2. Dependencies
+
+        2.1. Kamailio Modules
+        2.2. External Libraries or Applications
+
+   3. Parameters
+
+        3.1. db_url (string)
+        3.2. db_table (string)
+        3.3. username_column (string)
+        3.4. domain_column (string)
+        3.5. cpl_xml_column (string)
+        3.6. cpl_bin_column (string)
+        3.7. cpl_dtd_file (string)
+        3.8. log_dir (string)
+        3.9. proxy_recurse (int)
+        3.10. proxy_route (int)
+        3.11. case_sensitive (int)
+        3.12. realm_prefix (string)
+        3.13. timer_avp (string)
+        3.14. lookup_domain (string)
+        3.15. lookup_append_branches (int)
+        3.16. use_domain (integer)
+
+   4. Functions
+
+        4.1. cpl_run_script(type,mode, [uri])
+        4.2. cpl_process_register()
+        4.3. cpl_process_register_norpl()
+
+   5. RPC Commands
+
+        5.1. cpl.load
+        5.2. cpl.remove
+        5.3. cpl.get
+
+   6. Installation and Running
+
+        6.1. Database setup
+
+1. Overview
+
+   cpl-c modules implements a CPL (Call Processing Language) interpreter.
+   Support for uploading/downloading/removing scripts via SIP REGISTER
+   method is present.
+
+   CPL is an IETF specification detailed in RFC3880
+   (https://tools.ietf.org/html/rfc3880).
+
+2. Dependencies
+
+   2.1. Kamailio Modules
+   2.2. External Libraries or Applications
+
+2.1. Kamailio Modules
+
+   The following modules must be loaded before this module:
+     * any DB module- a DB module for interfacing the DB operations
+       (modules like mysql, postgres, dbtext, etc)
+     * TM (Transaction) module- used for proxying/forking requests
+     * SL (StateLess) module - used for sending stateless reply when
+       responding to REGISTER request or for sending back error responses
+     * USRLOC (User Location) module - used for implementing
+       lookup("registration") tag (adding into location set of the users'
+       contact)
+
+2.2. External Libraries or Applications
+
+   The following libraries or applications must be installed before
+   running Kamailio with this module loaded:
+     * libxml2 and libxml2-devel - on some SO, these to packages are
+       merged into libxml2. This library contains an engine for XML
+       parsing, DTD validation and DOM manipulation.
+
+3. Parameters
+
+   3.1. db_url (string)
+   3.2. db_table (string)
+   3.3. username_column (string)
+   3.4. domain_column (string)
+   3.5. cpl_xml_column (string)
+   3.6. cpl_bin_column (string)
+   3.7. cpl_dtd_file (string)
+   3.8. log_dir (string)
+   3.9. proxy_recurse (int)
+   3.10. proxy_route (int)
+   3.11. case_sensitive (int)
+   3.12. realm_prefix (string)
+   3.13. timer_avp (string)
+   3.14. lookup_domain (string)
+   3.15. lookup_append_branches (int)
+   3.16. use_domain (integer)
+
+3.1. db_url (string)
+
+   A SQL URL have to be given to the module for knowing where the database
+   containing the table with CPL scripts is locates. If required a user
+   name and password can be specified for allowing the module to connect
+   to the database server.
+
+   Default value is “mysql://kamailio:kamailiorw@localhost/kamailio”.
+
+   Example 1.1. Set db_url parameter
+...
+modparam("cpl-c","db_url","dbdriver://username:password@dbhost/dbname")
+...
+
+3.2. db_table (string)
+
+   Indicates the name of the table that store the CPL scripts. This table
+   must be locate into the database specified by “db_url” parameter. For
+   more about the format of the CPL table please see the
+   modules/cpl-c/init.mysql file.
+
+   Default value is “cpl”.
+
+   Example 1.2. Set db_table parameter
+...
+modparam("cpl-c","cpl_table","cpl")
+...
+
+3.3. username_column (string)
+
+   Indicates the name of the column used for storing the username.
+
+   Default value is “username”.
+
+   Example 1.3. Set username_column parameter
+...
+modparam("cpl-c","username_column","username")
+...
+
+3.4. domain_column (string)
+
+   Indicates the name of the column used for storing the domain.
+
+   Default value is “domain”.
+
+   Example 1.4. Set domain_column parameter
+...
+modparam("cpl-c","domain_column","domain")
+...
+
+3.5. cpl_xml_column (string)
+
+   Indicates the name of the column used for storing the the XML version
+   of the cpl script.
+
+   Default value is “cpl_xml”.
+
+   Example 1.5. Set cpl_xml_column parameter
+...
+modparam("cpl-c","cpl_xml_column","cpl_xml")
+...
+
+3.6. cpl_bin_column (string)
+
+   Indicates the name of the column used for storing the the binary
+   version of the cpl script (compiled version).
+
+   Default value is “cpl_bin”.
+
+   Example 1.6. Set cpl_bin_column parameter
+...
+modparam("cpl-c","cpl_bin_column","cpl_bin")
+...
+
+3.7. cpl_dtd_file (string)
+
+   Points to the DTD file describing the CPL grammar. The file name may
+   include also the path to the file. This path can be absolute or
+   relative (be careful the path will be relative to the starting
+   directory of Kamailio).
+
+   This parameter is MANDATORY!
+
+   Example 1.7. Set cpl_dtd_file parameter
+...
+modparam("cpl-c","cpl_dtd_file","/etc/kamailio/cpl-06.dtd")
+...
+
+3.8. log_dir (string)
+
+   Points to a directory where should be created all the log file
+   generated by the LOG CPL node. A log file per user will be created (on
+   demand) having the name username.log.
+
+   If this parameter is absent, the logging will be disabled without
+   generating error on execution.
+
+   Example 1.8. Set log_dir parameter
+...
+modparam("cpl-c","log_dir","/var/log/kamailio/cpl")
+...
+
+3.9. proxy_recurse (int)
+
+   Tells for how many time is allow to have recurse for PROXY CPL node If
+   it has value 2, when doing proxy, only twice the proxy action will be
+   re-triggered by a redirect response; the third time, the proxy
+   execution will end by going on REDIRECTION branch. The recurse feature
+   can be disable by setting this parameter to 0
+
+   Default value of this parameter is 0.
+
+   Example 1.9. Set proxy_recurse parameter
+...
+modparam("cpl-c","proxy_recurse",2)
+...
+
+3.10. proxy_route (int)
+
+   Before doing proxy (forward), a script route can be executed. All
+   modifications made by that route will be reflected only for the current
+   branch.
+
+   Default value of this parameter is 0 (none).
+
+   Example 1.10. Set proxy_route parameter
+...
+modparam("cpl-c","proxy_route",1)
+...
+
+3.11. case_sensitive (int)
+
+   Tells if the username matching should be perform case sensitive or not.
+   Set it to a non zero value to force a case sensitive handling of
+   usernames.
+
+   Default value of this parameter is 0.
+
+   Example 1.11. Set case_sensitive parameter
+...
+modparam("cpl-c","case_sensitive",1)
+...
+
+3.12. realm_prefix (string)
+
+   Defines a prefix for the domain part which should be ignored in
+   handling users and scripts.
+
+   Default value of this parameter is empty string.
+
+   Example 1.12. Set realm_prefix parameter
+...
+modparam("cpl-c","realm_prefix","sip.")
+...
+
+3.13. timer_avp (string)
+
+   Full specification (ID, NAME, ALIAS) of the AVP to be used to set the
+   value of the Final Response INVITE timeout - it's used by the TIMEOUT
+   attribute from the PROXY tag.
+
+   NOTE: take care and syncronize this value with the similar parameters
+   in TM module.
+
+   Default value of this parameter is NULL.
+
+   Example 1.13. Set timer_avp parameter
+...
+modparam("cpl-c","timer_avp","$avp(i:14)")
+...
+
+3.14. lookup_domain (string)
+
+   Used by lookup tag to indicate where to perform user location.
+   Basically this is the name of the usrloc domain (table) where the user
+   registrations are kept.
+
+   If set to empty string, the lookup node will be disabled - no user
+   location will be performed.
+
+   Default value of this parameter is NULL.
+
+   Example 1.14. Set lookup_domain parameter
+...
+modparam("cpl-c","lookup_domain","location")
+...
+
+3.15. lookup_append_branches (int)
+
+   Tells if the lookup tag should append branches (to do parallel forking)
+   if user_location lookup returns more than one contact. Set it to a non
+   zero value to enable parallel forking for location lookup tag.
+
+   Default value of this parameter is 0.
+
+   Example 1.15. Set lookup_append_branches parameter
+...
+modparam("cpl-c","lookup_append_branches",1)
+...
+
+3.16. use_domain (integer)
+
+   Indicates if the domain part of the URI should be used in user
+   identification (otherwise only username part will be used).
+
+   Default value is “0 (disabled)”.
+
+   Example 1.16. Set use_domain parameter
+...
+modparam("cpl-c","use_domain",1)
+...
+
+4. Functions
+
+   4.1. cpl_run_script(type,mode, [uri])
+   4.2. cpl_process_register()
+   4.3. cpl_process_register_norpl()
+
+4.1.  cpl_run_script(type,mode, [uri])
+
+   Starts the execution of the CPL script. The user name is fetched from
+   new_uri or requested uri or from To header -in this order- (for
+   incoming execution) or from FROM header (for outgoing execution).
+   Regarding the stateful/stateless message processing, the function is
+   very flexible, being able to run in different modes (see below
+   the"mode" parameter). Normally this function will end script execution.
+   There is no guaranty that the CPL script interpretation ended when
+   Kamailio script ended also (for the same INVITE ;-)) - this can happen
+   when the CPL script does a PROXY and the script interpretation pause
+   after proxying and it will be resume when some reply is received (this
+   can happen in a different process of SER). If the function returns to
+   script, the SIP server should continue with the normal behavior as if
+   no script existed. When some error is returned, the function itself
+   haven't sent any SIP error reply (this can be done from script).
+
+   Meaning of the parameters is as follows:
+     * type - which part of the script should be run; set it to "incoming"
+       for having the incoming part of script executed (when an INVITE is
+       received) or to "outgoing" for running the outgoing part of script
+       (when a user is generating an INVITE - call).
+     * mode - sets the interpreter mode as stateless/stateful behavior.
+       The following modes are accepted:
+          + IS_STATELESS - the current INVITE has no transaction created
+            yet. All replies (redirection or deny) will be done is a
+            stateless way. The execution will switch to stateful only when
+            proxy is done. So, if the function returns, will be in
+            stateless mode.
+          + IS_STATEFUL - the current INVITE has already a transaction
+            associated. All signaling operations (replies or proxy) will
+            be done in stateful way.So, if the function returns, will be
+            in stateful mode.
+          + FORCE_STATEFUL - the current INVITE has no transaction created
+            yet. All signaling operations will be done is a stateful way
+            (on signaling, the transaction will be created from within the
+            interpreter). So, if the function returns, will be in
+            stateless mode.
+       HINT: is_stateful is very difficult to manage from the routing
+       script (script processing can continue in stateful mode);
+       is_stateless is the fastest and less resources consumer
+       (transaction is created only if proxying is done), but there is
+       minimal protection against retransmissions (since replies are send
+       stateless); force_stateful is a good compromise - all signaling is
+       done stateful (retransmission protection) and in the same time, if
+       returning to script, it will be in stateless mode (easy to continue
+       the routing script execution)
+     * uri - optional - provide the SIP URI to be used for loading the CPL
+       script, instead of taking it from R-URI or headers.
+
+   This function can be used from REQUEST_ROUTE.
+
+   Example 1.17. cpl_run_script usage
+...
+cpl_run_script("incoming","force_stateful");
+...
+
+4.2.  cpl_process_register()
+
+   This function MUST be called only for REGISTER requests. It checks if
+   the current REGISTER request is related or not with CPL script
+   upload/download/ remove. If it is, all the needed operation will be
+   done. For checking if the REGISTER is CPL related, the function looks
+   fist to "Content-Type" header. If it exists and has a the mime type set
+   to "application/cpl+xml" means this is a CPL script upload/remove
+   operation. The distinction between to case is made by looking at
+   "Content-Disposition" header; id its value is "script;action=store",
+   means it's an upload; if it's "script;action=remove", means it's a
+   remove operation; other values are considered to be errors. If no
+   "Content-Type" header is present, the function looks to "Accept" header
+   and if it contains the "*" or "application/cpl-xml" the request it will
+   be consider one for downloading CPL scripts. The functions returns to
+   script only if the REGISTER is not related to CPL. In other case, the
+   function will send by itself the necessary replies (stateless - using
+   sl), including for errors.
+
+   This function can be used from REQUEST_ROUTE.
+
+   Example 1.18. cpl_process_register usage
+...
+if (method=="REGISTER") {
+    cpl_process_register();
+}
+...
+
+4.3.  cpl_process_register_norpl()
+
+   Same as “cpl_process_register” without internally generating the reply.
+   All information (script) is appended to the reply but without sending
+   it out.
+
+   Main purpose of this function is to allow integration between CPL and
+   UserLocation services via same REGISTER messages.
+
+   This function can be used from REQUEST_ROUTE.
+
+   Example 1.19. cpl_process_register_norpl usage
+...
+if (method=="REGISTER") {
+    cpl_process_register();
+    # continue with usrloc part
+    save("location");
+}
+...
+
+5. RPC Commands
+
+   5.1. cpl.load
+   5.2. cpl.remove
+   5.3. cpl.get
+
+5.1. cpl.load
+
+   For the given user, loads the XML cpl file, compiles it into binary
+   format and stores both format into database.
+
+   Name: cpl.load
+
+   Parameters:
+     * username : name of the user
+     * cpl_filename: file name
+
+   RPC Command format:
+...
+kamcmd cpl.load username cpl_filename
+...
+
+5.2. cpl.remove
+
+   For the given user, removes the entire database record (XML cpl and
+   binary cpl); user with empty cpl scripts are not accepted.
+
+   Name: cpl.remove
+
+   Parameters:
+     * username : name of the user
+
+   RPC Command format:
+...
+kamcmd cpl.remove username
+...
+
+5.3. cpl.get
+
+   For the given user, returns the CPL script in XML format.
+
+   Name: cpl.get
+
+   Parameters:
+     * username : name of the user
+
+   RPC Command format:
+...
+kamcmd cpl.get username
+...
+
+6. Installation and Running
+
+   6.1. Database setup
+
+6.1. Database setup
+
+   Before running Kamailio with cpl-c, you have to setup the database
+   table where the module will store the CPL scripts. For that, if the
+   table was not created by the installation script or you choose to
+   install everything by yourself you can use the cpc-create.sql SQL
+   script in the database directories in the kamailio/scripts folder as
+   template. Database and table name can be set with module parameters so
+   they can be changed, but the name of the columns must be as they are in
+   the SQL script. You can also find the complete database documentation
+   on the project webpage,
+   http://www.kamailio.org/docs/db-tables/kamailio-db-devel.html.