"Fossies" - the Fresh Open Source Software Archive

Member "opensips-3.0.1/modules/presence_callinfo/README" (1 Oct 2019, 13174 Bytes) of package /linux/misc/opensips-3.0.1.tar.gz:


As a special service "Fossies" has tried to format the requested text file into HTML format (style: standard) with prefixed line numbers. Alternatively you can here view or download the uninterpreted source code file. See also the latest Fossies "Diffs" side-by-side code changes report for "README": 3.0.0_vs_3.0.1.

    1 Presence_CallInfo Module
    2      __________________________________________________________
    3 
    4    Table of Contents
    5 
    6    1. Admin Guide
    7 
    8         1.1. Overview
    9         1.2. Usage modes
   10 
   11               1.2.1. External publishing
   12               1.2.2. Internal publishing
   13 
   14         1.3. Dependencies
   15 
   16               1.3.1. OpenSIPS Modules
   17               1.3.2. External Libraries or Applications
   18 
   19         1.4. Exported Parameters
   20 
   21               1.4.1. call_info_timeout_notification (int)
   22               1.4.2. line_seize_timeout_notification (int)
   23               1.4.3. disable_dialog_support_for_sca (int)
   24               1.4.4. line_hash_size (int)
   25 
   26         1.5. Exported Functions
   27 
   28               1.5.1. sca_set_calling_line([line])
   29               1.5.2. sca_set_called_line([line])
   30 
   31    2. Contributors
   32 
   33         2.1. By Commit Statistics
   34         2.2. By Commit Activity
   35 
   36    3. Documentation
   37 
   38         3.1. Contributors
   39 
   40    List of Tables
   41 
   42    2.1. Top contributors by DevScore^(1), authored commits^(2) and
   43           lines added/removed^(3)
   44 
   45    2.2. Most recently active contributors^(1) to this module
   46 
   47    List of Examples
   48 
   49    1.1. Set call_info_timeout_notification parameter
   50    1.2. Set line_seize_timeout_notification parameter
   51    1.3. Set disable_dialog_support_for_sca parameter
   52    1.4. Set line_hash_size parameter
   53    1.5. sca_set_calling_line() usage
   54    1.6. sca_set_called_line() usage
   55 
   56 Chapter 1. Admin Guide
   57 
   58 1.1. Overview
   59 
   60    This module provides OpenSIPS support for shared call
   61    appearances (SCA) as defined by BroadWorks SIP Access Side
   62    Extensions Interface specifications. The SCA mechanism is a
   63    fundamental building block for a variety of enhanced telephony
   64    services. Features like attendant console, line extensions, and
   65    key system emulation cannot be delivered without some mechanism
   66    for sharing call appearances across access devices. Although
   67    SIP (RFC 3261) by itself offers no inherent semantics for
   68    supporting SCA features, when coupled with an appropriate
   69    instantiation of the “SIP Specific Event Notification”
   70    framework (RFC 3265), these services can be deployed quite
   71    easily in a distributed network.
   72 
   73    A shared line is an address of record managed by central
   74    controlling element, such as an application server. The
   75    application server allows multiple endpoints to register
   76    locations against the address of record. The application server
   77    is responsible for policing who can register and who cannot
   78    register against the shared line.
   79 
   80    The module enables the handling of "call-info" and "line-seize"
   81    events inside the presence module. It is used with the general
   82    event handling module: presence and it constructs and adds
   83    "Call-Info" headers to notification events.
   84 
   85 1.2. Usage modes
   86 
   87    The module can be used in two ways (depending on who is doing
   88    the publishing of the "call-info" data:
   89      * external publishing - the "call-info" data is received from
   90        a third party via SIP PUBLISH requests. In this mode, the
   91        modules simply distributes the SCA info, it is not
   92        producing any of it - a third-party application must
   93        publish "call-info" events to the presence server.
   94      * internal publishing - the "call-info" data is internally
   95        generated by the module, based on the information received
   96        from the dialog module - what calls are using what
   97        line/index, what is the state of the call, etc. There is no
   98        SIP PUBLISH in this case and there is no need for a
   99        third-party - the module is self-sufficient and stand alone
  100        as functionality.
  101 
  102    The used mode can be controlled via the module parameter
  103    "disable_dialog_support_for_sca" - see below in the parameter's
  104    section.
  105 
  106 1.2.1. External publishing
  107 
  108    The module does not currently implement any authorization
  109    rules. It assumes that publish requests are only issued by a
  110    third-party application and subscribe requests only by
  111    subscriber to call-info and line-seize events. Authorization
  112    can thus be easily done by OpenSIPS configuration file before
  113    calling handle_publish() and handle_subscribe() functions.
  114 
  115    To get better understanding on how the module works please take
  116    a look at the follwing figure:
  117 
  118    caller       proxy &   callee        watcher        publisher
  119 alice@example  presence  bob@example  watcher@example
  120                  server
  121      |             |           |           |              |
  122      |             |<-----SUBSCRIBE bob----|              |
  123      |             |------200 OK---------->|              |
  124      |             |------NOTIFY---------->|              |
  125      |             |<-----200 OK-----------|              |
  126      |             |           |           |              |
  127      |--INV bob--->|           |           |              |
  128      |             |--INV bob->|           |              |
  129      |             |<-100------|           |              |
  130      |             |<-----PUBLISH(alerting)---------------|
  131      |             |------200 OK------------------------->|
  132      |             |------NOTIFY---------->|              |
  133      |             |<-----200 OK-----------|              |
  134      |             |           |           |              |
  135      |             |<-180 ring-|           |              |
  136      |<--180 ring--|           |           |              |
  137      |             |           |           |              |
  138      |             |           |           |              |
  139      |             |<-200 OK---|           |              |
  140      |<--200 OK----|           |           |              |
  141      |             |<-----PUBLISH(active)-----------------|
  142      |             |------200 OK------------------------->|
  143      |             |------NOTIFY---------->|              |
  144      |             |<-----200 OK-----------|              |
  145      |             |           |           |              |
  146 
  147 
  148      * The watcher subscribes the "Event: dialog" of Bob.
  149      * Alice calls Bob.
  150      * The publisher is publishing the "alerting" state for Bob.
  151      * PUBLISH is received and handled by presence module.
  152        Presence module updates the "presentity". Presence module
  153        checks for active watchers of the presentity. The active
  154        watcher is notified via a NOTIFY SIP request.
  155      * Bob answers the call.
  156      * The publisher is publishing the "active" state for Bob.
  157      * PUBLISH is received and handled by presence module.
  158        Presence module updates the "presentity". Presence module
  159        checks for active watchers of the presentity. The active
  160        watcher is notified via a NOTIFY SIP request.
  161 
  162 1.2.2. Internal publishing
  163 
  164    In this mode, the module requires the "dialog" module to be
  165    loaded into OpenSIPS. All the publishing will be automatically
  166    done (the modules will exchange data directly via C API).
  167 
  168    From presence perspective, the OpenSIPS script must be
  169    configured to handle the SUBSCRIBE requests only (there is no
  170    need for PUBLISH handling as there is no SIP publishing in this
  171    mode). So be sure to use the "handle_subscribe()" function
  172    (from presence module) in the script.
  173 
  174    To trigger the internal publishing (from the dialog module) for
  175    a certain call, use the "sca_set_calling_line()" or
  176    "sca_set_called_line()" functions from the script when handling
  177    a new call. These functions will do all the work (creating
  178    dialog, setting the internal publishing, etc) - you just need
  179    to use them and eventually specify the name of the line (if
  180    other then the one from the SIP INVITE) - see the below
  181    documentation.
  182 
  183    LIMITATIONS : in this mode, the module does not really check if
  184    the line exists or not (like defined) - it blindly trust the
  185    traffic; also there is no check on how many indexes are for
  186    each line. Such information (lines and indexes) are not
  187    provisioned into the module, but the module will dynamically
  188    accept and handle any line and index based on the SIP traffic.
  189 
  190 1.3. Dependencies
  191 
  192 1.3.1. OpenSIPS Modules
  193 
  194    The following modules must be loaded before this module:
  195      * presence.
  196      * dialog.
  197 
  198 1.3.2. External Libraries or Applications
  199 
  200    None.
  201 
  202 1.4. Exported Parameters
  203 
  204 1.4.1. call_info_timeout_notification (int)
  205 
  206    Enables or disables call_info event timeout notifications.
  207 
  208    Default value is “1” (enabled).
  209 
  210    Example 1.1. Set call_info_timeout_notification parameter
  211 ...
  212 modparam("presence_callinfo", "call_info_timeout_notification", 0)
  213 ...
  214 
  215 1.4.2. line_seize_timeout_notification (int)
  216 
  217    Enables or disables line_seize event timeout notifications.
  218 
  219    Default value is “0” (disabled).
  220 
  221    Example 1.2. Set line_seize_timeout_notification parameter
  222 ...
  223 modparam("presence_callinfo", "line_seize_timeout_notification", 1)
  224 ...
  225 
  226 1.4.3. disable_dialog_support_for_sca (int)
  227 
  228    Disables the internal publishing of the "call-info" events
  229    (generated by the dialog module). The publishing is expected to
  230    be done via SIP PUBLISH from a third-party. See the wroking
  231    mode described in the beginning of this document.
  232 
  233    Default value is “0” (not disabled).
  234 
  235    Example 1.3. Set disable_dialog_support_for_sca parameter
  236 ...
  237 modparam("presence_callinfo", "disable_dialog_support_for_sca", 1)
  238 ...
  239 
  240 1.4.4. line_hash_size (int)
  241 
  242    Allows you to controll the size of the internal hash table used
  243    for storing the information about the lines and indexes (in the
  244    internal publishing mode).
  245 
  246    The value must be a power of 2. You may consider increasing the
  247    value if using a large set of lines (>1000).
  248 
  249    Default value is “64”.
  250 
  251    Example 1.4. Set line_hash_size parameter
  252 ...
  253 modparam("presence_callinfo", "line_hash_size", 128)
  254 ...
  255 
  256 1.5. Exported Functions
  257 
  258 1.5.1.  sca_set_calling_line([line])
  259 
  260    The function (to be used only in internal publishing mode) is
  261    setting for the current new call (initinal INVITE) the outbound
  262    line - the line used for calling out.
  263 
  264    If no parameter is provided, the name of the line is taken from
  265    the SIP FROM header of the INVITE. You can override that by
  266    providing the name of the line as a string parameter - be
  267    careful as the value must be a SIP URI !
  268 
  269    This function can be used from REQUEST_ROUTE.
  270 
  271    Example 1.5. sca_set_calling_line() usage
  272 ...
  273         if (is_method("INVITE") and !has_totag()) {
  274                 sca_set_calling_line();
  275         }
  276 ...
  277 
  278 1.5.2.  sca_set_called_line([line])
  279 
  280    The function (to be used only in internal publishing mode) is
  281    setting for the current new call (initinal INVITE) the inbound
  282    line - the line the call was received on.
  283 
  284    If no parameter is provided, the name of the line is taken from
  285    the SIP RURI of the INVITE. You can override that by providing
  286    the name of the line as a string parameter - be careful as the
  287    value must be a SIP URI ! Variables are accepted.
  288 
  289    This function can be used from REQUEST_ROUTE.
  290 
  291    Example 1.6. sca_set_called_line() usage
  292 ...
  293         if (is_method("INVITE") and !has_totag()) {
  294                 sca_set_called_line();
  295         }
  296 ...
  297 
  298 Chapter 2. Contributors
  299 
  300 2.1. By Commit Statistics
  301 
  302    Table 2.1. Top contributors by DevScore^(1), authored
  303    commits^(2) and lines added/removed^(3)
  304      Name DevScore Commits Lines ++ Lines --
  305    1. Bogdan-Andrei Iancu (@bogdan-iancu) 21 7 1407 58
  306    2. Ovidiu Sas (@ovidiusas) 12 6 577 7
  307    3. Razvan Crainea (@razvancrainea) 10 8 22 14
  308    4. Liviu Chircu (@liviuchircu) 9 7 42 52
  309    5. Vlad Patrascu (@rvlad-patrascu) 5 3 23 54
  310    6. Walter Doekes (@wdoekes) 3 1 2 2
  311    7. Peter Lemenkov (@lemenkov) 3 1 1 1
  312 
  313    (1) DevScore = author_commits + author_lines_added /
  314    (project_lines_added / project_commits) + author_lines_deleted
  315    / (project_lines_deleted / project_commits)
  316 
  317    (2) including any documentation-related commits, excluding
  318    merge commits. Regarding imported patches/code, we do our best
  319    to count the work on behalf of the proper owner, as per the
  320    "fix_authors" and "mod_renames" arrays in
  321    opensips/doc/build-contrib.sh. If you identify any
  322    patches/commits which do not get properly attributed to you,
  323    please submit a pull request which extends "fix_authors" and/or
  324    "mod_renames".
  325 
  326    (3) ignoring whitespace edits, renamed files and auto-generated
  327    files
  328 
  329 2.2. By Commit Activity
  330 
  331    Table 2.2. Most recently active contributors^(1) to this module
  332                      Name                   Commit Activity
  333    1. Razvan Crainea (@razvancrainea)     Oct 2011 - Sep 2019
  334    2. Vlad Patrascu (@rvlad-patrascu)     May 2017 - Apr 2019
  335    3. Bogdan-Andrei Iancu (@bogdan-iancu) Jan 2013 - Apr 2019
  336    4. Peter Lemenkov (@lemenkov)          Jun 2018 - Jun 2018
  337    5. Liviu Chircu (@liviuchircu)         Mar 2014 - Jun 2018
  338    6. Walter Doekes (@wdoekes)            Mar 2014 - Mar 2014
  339    7. Ovidiu Sas (@ovidiusas)             Dec 2010 - Mar 2011
  340 
  341    (1) including any documentation-related commits, excluding
  342    merge commits
  343 
  344 Chapter 3. Documentation
  345 
  346 3.1. Contributors
  347 
  348    Last edited by: Vlad Patrascu (@rvlad-patrascu), Peter Lemenkov
  349    (@lemenkov), Liviu Chircu (@liviuchircu), Bogdan-Andrei Iancu
  350    (@bogdan-iancu), Ovidiu Sas (@ovidiusas).
  351 
  352    Documentation Copyrights:
  353 
  354    Copyright © 2010-2013 VoIP Embedded, Inc.