Presence_CallInfo Module
     __________________________________________________________

   Table of Contents

   1. Admin Guide

        1.1. Overview
        1.2. Usage modes

              1.2.1. External publishing
              1.2.2. Internal publishing

        1.3. Dependencies

              1.3.1. OpenSIPS Modules
              1.3.2. External Libraries or Applications

        1.4. Exported Parameters

              1.4.1. call_info_timeout_notification (int)
              1.4.2. line_seize_timeout_notification (int)
              1.4.3. disable_dialog_support_for_sca (int)
              1.4.4. line_hash_size (int)

        1.5. Exported Functions

              1.5.1. sca_set_calling_line([line])
              1.5.2. sca_set_called_line([line])

   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 call_info_timeout_notification parameter
   1.2. Set line_seize_timeout_notification parameter
   1.3. Set disable_dialog_support_for_sca parameter
   1.4. Set line_hash_size parameter
   1.5. sca_set_calling_line() usage
   1.6. sca_set_called_line() usage

Chapter 1. Admin Guide

1.1. Overview

   This module provides OpenSIPS support for shared call
   appearances (SCA) as defined by BroadWorks SIP Access Side
   Extensions Interface specifications. The SCA mechanism is a
   fundamental building block for a variety of enhanced telephony
   services. Features like attendant console, line extensions, and
   key system emulation cannot be delivered without some mechanism
   for sharing call appearances across access devices. Although
   SIP (RFC 3261) by itself offers no inherent semantics for
   supporting SCA features, when coupled with an appropriate
   instantiation of the “SIP Specific Event Notification”
   framework (RFC 3265), these services can be deployed quite
   easily in a distributed network.

   A shared line is an address of record managed by central
   controlling element, such as an application server. The
   application server allows multiple endpoints to register
   locations against the address of record. The application server
   is responsible for policing who can register and who cannot
   register against the shared line.

   The module enables the handling of "call-info" and "line-seize"
   events inside the presence module. It is used with the general
   event handling module: presence and it constructs and adds
   "Call-Info" headers to notification events.

1.2. Usage modes

   The module can be used in two ways (depending on who is doing
   the publishing of the "call-info" data:
     * external publishing - the "call-info" data is received from
       a third party via SIP PUBLISH requests. In this mode, the
       modules simply distributes the SCA info, it is not
       producing any of it - a third-party application must
       publish "call-info" events to the presence server.
     * internal publishing - the "call-info" data is internally
       generated by the module, based on the information received
       from the dialog module - what calls are using what
       line/index, what is the state of the call, etc. There is no
       SIP PUBLISH in this case and there is no need for a
       third-party - the module is self-sufficient and stand alone
       as functionality.

   The used mode can be controlled via the module parameter
   "disable_dialog_support_for_sca" - see below in the parameter's
   section.

1.2.1. External publishing

   The module does not currently implement any authorization
   rules. It assumes that publish requests are only issued by a
   third-party application and subscribe requests only by
   subscriber to call-info and line-seize events. Authorization
   can thus be easily done by OpenSIPS configuration file before
   calling handle_publish() and handle_subscribe() functions.

   To get better understanding on how the module works please take
   a look at the follwing figure:

   caller       proxy &   callee        watcher        publisher
alice@example  presence  bob@example  watcher@example
                 server
     |             |           |           |              |
     |             |<-----SUBSCRIBE bob----|              |
     |             |------200 OK---------->|              |
     |             |------NOTIFY---------->|              |
     |             |<-----200 OK-----------|              |
     |             |           |           |              |
     |--INV bob--->|           |           |              |
     |             |--INV bob->|           |              |
     |             |<-100------|           |              |
     |             |<-----PUBLISH(alerting)---------------|
     |             |------200 OK------------------------->|
     |             |------NOTIFY---------->|              |
     |             |<-----200 OK-----------|              |
     |             |           |           |              |
     |             |<-180 ring-|           |              |
     |<--180 ring--|           |           |              |
     |             |           |           |              |
     |             |           |           |              |
     |             |<-200 OK---|           |              |
     |<--200 OK----|           |           |              |
     |             |<-----PUBLISH(active)-----------------|
     |             |------200 OK------------------------->|
     |             |------NOTIFY---------->|              |
     |             |<-----200 OK-----------|              |
     |             |           |           |              |


     * The watcher subscribes the "Event: dialog" of Bob.
     * Alice calls Bob.
     * The publisher is publishing the "alerting" state for Bob.
     * PUBLISH is received and handled by presence module.
       Presence module updates the "presentity". Presence module
       checks for active watchers of the presentity. The active
       watcher is notified via a NOTIFY SIP request.
     * Bob answers the call.
     * The publisher is publishing the "active" state for Bob.
     * PUBLISH is received and handled by presence module.
       Presence module updates the "presentity". Presence module
       checks for active watchers of the presentity. The active
       watcher is notified via a NOTIFY SIP request.

1.2.2. Internal publishing

   In this mode, the module requires the "dialog" module to be
   loaded into OpenSIPS. All the publishing will be automatically
   done (the modules will exchange data directly via C API).

   From presence perspective, the OpenSIPS script must be
   configured to handle the SUBSCRIBE requests only (there is no
   need for PUBLISH handling as there is no SIP publishing in this
   mode). So be sure to use the "handle_subscribe()" function
   (from presence module) in the script.

   To trigger the internal publishing (from the dialog module) for
   a certain call, use the "sca_set_calling_line()" or
   "sca_set_called_line()" functions from the script when handling
   a new call. These functions will do all the work (creating
   dialog, setting the internal publishing, etc) - you just need
   to use them and eventually specify the name of the line (if
   other then the one from the SIP INVITE) - see the below
   documentation.

   LIMITATIONS : in this mode, the module does not really check if
   the line exists or not (like defined) - it blindly trust the
   traffic; also there is no check on how many indexes are for
   each line. Such information (lines and indexes) are not
   provisioned into the module, but the module will dynamically
   accept and handle any line and index based on the SIP traffic.

1.3. Dependencies

1.3.1. OpenSIPS Modules

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

1.3.2. External Libraries or Applications

   None.

1.4. Exported Parameters

1.4.1. call_info_timeout_notification (int)

   Enables or disables call_info event timeout notifications.

   Default value is “1” (enabled).

   Example 1.1. Set call_info_timeout_notification parameter
...
modparam("presence_callinfo", "call_info_timeout_notification", 0)
...

1.4.2. line_seize_timeout_notification (int)

   Enables or disables line_seize event timeout notifications.

   Default value is “0” (disabled).

   Example 1.2. Set line_seize_timeout_notification parameter
...
modparam("presence_callinfo", "line_seize_timeout_notification", 1)
...

1.4.3. disable_dialog_support_for_sca (int)

   Disables the internal publishing of the "call-info" events
   (generated by the dialog module). The publishing is expected to
   be done via SIP PUBLISH from a third-party. See the wroking
   mode described in the beginning of this document.

   Default value is “0” (not disabled).

   Example 1.3. Set disable_dialog_support_for_sca parameter
...
modparam("presence_callinfo", "disable_dialog_support_for_sca", 1)
...

1.4.4. line_hash_size (int)

   Allows you to controll the size of the internal hash table used
   for storing the information about the lines and indexes (in the
   internal publishing mode).

   The value must be a power of 2. You may consider increasing the
   value if using a large set of lines (>1000).

   Default value is “64”.

   Example 1.4. Set line_hash_size parameter
...
modparam("presence_callinfo", "line_hash_size", 128)
...

1.5. Exported Functions

1.5.1.  sca_set_calling_line([line])

   The function (to be used only in internal publishing mode) is
   setting for the current new call (initinal INVITE) the outbound
   line - the line used for calling out.

   If no parameter is provided, the name of the line is taken from
   the SIP FROM header of the INVITE. You can override that by
   providing the name of the line as a string parameter - be
   careful as the value must be a SIP URI !

   This function can be used from REQUEST_ROUTE.

   Example 1.5. sca_set_calling_line() usage
...
        if (is_method("INVITE") and !has_totag()) {
                sca_set_calling_line();
        }
...

1.5.2.  sca_set_called_line([line])

   The function (to be used only in internal publishing mode) is
   setting for the current new call (initinal INVITE) the inbound
   line - the line the call was received on.

   If no parameter is provided, the name of the line is taken from
   the SIP RURI of the INVITE. You can override that by providing
   the name of the line as a string parameter - be careful as the
   value must be a SIP URI ! Variables are accepted.

   This function can be used from REQUEST_ROUTE.

   Example 1.6. sca_set_called_line() usage
...
        if (is_method("INVITE") and !has_totag()) {
                sca_set_called_line();
        }
...

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. Bogdan-Andrei Iancu (@bogdan-iancu) 20 7 1407 58
   2. Ovidiu Sas (@ovidiusas) 12 6 577 7
   3. Razvan Crainea (@razvancrainea) 10 8 22 14
   4. Liviu Chircu (@liviuchircu) 9 7 42 52
   5. Vlad Patrascu (@rvlad-patrascu) 7 4 45 67
   6. Maksym Sobolyev (@sobomax) 6 4 5 6
   7. Walter Doekes (@wdoekes) 3 1 2 2
   8. 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. Vlad Patrascu (@rvlad-patrascu)     May 2017 - Mar 2023
   2. Maksym Sobolyev (@sobomax)          Jan 2021 - Feb 2023
   3. Razvan Crainea (@razvancrainea)     Oct 2011 - Sep 2019
   4. Bogdan-Andrei Iancu (@bogdan-iancu) Jan 2013 - Apr 2019
   5. Peter Lemenkov (@lemenkov)          Jun 2018 - Jun 2018
   6. Liviu Chircu (@liviuchircu)         Mar 2014 - Jun 2018
   7. Walter Doekes (@wdoekes)            Mar 2014 - Mar 2014
   8. Ovidiu Sas (@ovidiusas)             Dec 2010 - Mar 2011

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

Chapter 3. Documentation

3.1. Contributors

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

   Documentation Copyrights:

   Copyright © 2010-2013 VoIP Embedded, Inc.
