obsolete/cpl-c/README
d9bb387b
 1. CPL Module
baa62270
 
9b6c6de6
 Bogdan-Andrei Iancu
baa62270
 
    FhG FOKUS
 
d9bb387b
    Copyright © 2003 FhG FOKUS
      __________________________________________________________________
baa62270
 
d9bb387b
    1.1. Overview
    1.2. Dependencies
baa62270
 
d9bb387b
         1.2.1. SER Modules
         1.2.2. External Libraries or Applications
baa62270
 
d9bb387b
    1.3. Parameters
baa62270
 
d9bb387b
         1.3.1. cpl_db (string)
         1.3.2. cpl_table (string)
         1.3.3. cpl_dtd_file (string)
         1.3.4. log_dir (string)
         1.3.5. proxy_recurse (int)
         1.3.6. proxy_route (int)
         1.3.7. nat_flag (int)
         1.3.8. lookup_domain (int)
baa62270
 
d9bb387b
    1.4. Functions
baa62270
 
d9bb387b
         1.4.1. cpl_run_script(type,mode)
         1.4.2. cpl_process_register()
baa62270
 
 1.1. Overview
 
d9bb387b
    cpl-c modules implements a CPL (Call Processing Language) interpreter.
    Support for uploading/downloading/removing scripts via SIP REGISTER
    method is implemented.
baa62270
 
 1.2. Dependencies
 
 1.2.1. SER Modules
 
    The following modules must be loaded before this module:
d9bb387b
      * tm.  Transaction Manager, 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") (adding into location set of the users'
        contact)
baa62270
 
 1.2.2. External Libraries or Applications
 
d9bb387b
    The following libraries or applications must be installed before
    running SER with this module loaded:
      * libxml2.  This library contains an engine for XML parsing, DTD
        validation and DOM manipulation.
baa62270
 
d9bb387b
 1.3. Parameters
baa62270
 
9b6c6de6
 1.3.1. cpl_db (string)
baa62270
 
d9bb387b
    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.
 
 Warning
baa62270
 
d9bb387b
    This parameter is mandatory.
baa62270
 
d9bb387b
    Example 1. Set cpl_db parameter
baa62270
 ...
af1d4a45
 modparam("cpl_c","cpl_db","mysql://user:passwd@host/database")
baa62270
 ...
9b6c6de6
 
 1.3.2. cpl_table (string)
 
d9bb387b
    Indicates the name of the table that store the CPL scripts. This table
    must be locate into the database specified by "cpl_db" parameter. For
    more about the format of the CPL table please see
    modules/cpl-c/init.mysql.
 
 Warning
9b6c6de6
 
d9bb387b
    This parameter is mandatory.
9b6c6de6
 
d9bb387b
    Example 2. Set cpl_table parameter
9b6c6de6
 ...
0dd88a0e
 modparam("cpl_c","cpl_table","cpltable")
9b6c6de6
 ...
 
0dd88a0e
 1.3.3. cpl_dtd_file (string)
9b6c6de6
 
d9bb387b
    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 SER).
9b6c6de6
 
d9bb387b
 Warning
9b6c6de6
 
d9bb387b
    This parameter is mandatory.
 
    Example 3. Set cpl_dtd_file parameter
9b6c6de6
 ...
 modparam("cpl_c","cpl_dtd_file","/etc/ser/cpl-06.dtd")
 ...
 
0dd88a0e
 1.3.4. log_dir (string)
9b6c6de6
 
0dd88a0e
    Points to a directory where should be created all the log file
d9bb387b
    generated by the LOG CPL node. A log file per user will be created (on
    demand) having the name username.log.
 
 Note
0dd88a0e
 
d9bb387b
    If this parameter is absent, the logging will be disabled without
    generating error on execution.
9b6c6de6
 
d9bb387b
    Example 4. Set log_dir parameter
9b6c6de6
 ...
0dd88a0e
 modparam("cpl_c","log_dir","/var/log/ser/cpl")
9b6c6de6
 ...
 
0dd88a0e
 1.3.5. proxy_recurse (int)
9b6c6de6
 
d9bb387b
    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
0dd88a0e
 
d9bb387b
    Default value of this parameter is 0.
9b6c6de6
 
d9bb387b
    Example 5. Set proxy_recurse parameter
9b6c6de6
 ...
 modparam("cpl_c","proxy_recurse",2)
 ...
baa62270
 
af1d4a45
 1.3.6. proxy_route (int)
 
d9bb387b
    Before doing proxy (forward), a script route can be executed. All
    modifications made by that route will be reflected only for the current
    branch.
af1d4a45
 
d9bb387b
    Default value of this parameter is 0 (none).
af1d4a45
 
d9bb387b
    Example 6. Set proxy_route parameter
af1d4a45
 ...
 modparam("cpl_c","proxy_route",1)
 ...
 
 1.3.7. nat_flag (int)
 
d9bb387b
    Sets the flag used for marking calls via NAT. Used by lookup tag when
    retrieving a contact behind a NAT (this flag will be set).
af1d4a45
 
d9bb387b
    Default value of this parameter is 6.
af1d4a45
 
d9bb387b
    Example 7. Set nat_flag parameter
af1d4a45
 ...
 modparam("cpl_c","nat_flag",4)
 ...
 
 1.3.8. lookup_domain (int)
 
d9bb387b
    Tells if the lookup tag should use or not the domain part when doing
    user location search. Set it to a non zero value to force also domain
    matching.
af1d4a45
 
d9bb387b
    Default value of this parameter is 0.
af1d4a45
 
d9bb387b
    Example 8. Set lookup_domain parameter
af1d4a45
 ...
 modparam("cpl_c","lookup_domain",1)
 ...
baa62270
 
d9bb387b
 1.4. Functions
baa62270
 
d9bb387b
 1.4.1.  cpl_run_script(type,mode)
baa62270
 
d9bb387b
    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 ser
    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).
baa62270
 
d9bb387b
    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.
baa62270
 
d9bb387b
 Note
        is_stateful is very difficult to manage from the routing script
        (script processing can continue in stateful mode); is_stateless is
        the fastest and consumes less resources (transaction is created
        only if proxying is done), but there is only a minimal protection
        against retransmissions (since replies are send statelessly);
        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)
baa62270
 
d9bb387b
    Example 9. cpl_run_script usage
 ...
 cpl_run_script("incoming","force_stateful");
 ...
baa62270
 
d9bb387b
 1.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.