presence_dfks Module
     __________________________________________________________

   Table of Contents

   1. Admin Guide

        1.1. Overview
        1.2. Dependencies

              1.2.1. OpenSIPS Modules
              1.2.2. External Libraries or Applications

        1.3. Exported Parameters

              1.3.1. get_route (string)
              1.3.2. set_route (string)

        1.4. Exported Functions
        1.5. Exported MI Functions

              1.5.1. dfks_set_feature

        1.6. Exported Pseudo-Variables

              1.6.1. $dfks(field)

   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 parameter
   1.2. Set parameter
   1.3. dfks usage

Chapter 1. Admin Guide

1.1. Overview

   The module enables the handling of the "as-feature-event" event
   package (as defined by Broadsoft's Device Feature Key
   Synchronization protocol) by the presence module. This can be
   used to synchronize the status of features such as Do Not
   Disturb and different forwarding types between a SIP phone and
   a SIP server.

   The module supports synchronization for the following features:
   Do Not Disturb, Call Forwarding Always, Call Forwarding Busy
   and Call Forwarding No Answer. Feature status can be changed
   either from the SIP phone or the OpenSIPS Server( by running an
   MI command).

   When handling a SUBSCRIBE message without a body, the module
   will run a script route for each feature, that will be used to
   retrieve the current status of that feature. Conversely, a
   SUBSCRIBE with a body will trigger a script route where the
   updated status of a specific feature is available. This route
   might also be run if the feature update was triggered from
   OpenSIPS via MI.

   Note that the module does not automatically cache or persist
   any feature information as this is left for the script writer
   to implement in the routes triggered by the module.

1.2. Dependencies

1.2.1. OpenSIPS Modules

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

1.2.2. External Libraries or Applications

     * libxml2-dev.

1.3. Exported Parameters

1.3.1. get_route (string)

   The name of the script route to be run in order to retrieve the
   status of a feature.

   Default value is “dfks_get”.

   Example 1.1. Set parameter
...
modparam("presence_dfks", "get_route", "dfks_get")
...

1.3.2. set_route (string)

   The name of the script route to be run when a feature status
   update from a SIP phone is received.

   Default value is “dfks_get”.

   Example 1.2. Set parameter
...
modparam("presence_dfks", "set_route", "dfks_set")
...

1.4. Exported Functions

   None.

1.5. Exported MI Functions

1.5.1.  dfks_set_feature

   Triggers the sending of NOTIFY messages containing a feature
   status update to all watchers.

   Note: calling this MI function also triggers the set_route run.
   One can determine if the route is triggered by an MI function
   by checking the existence of the $dfks(param) variable.

   Name: dfks_set_feature

   Parameters:
     * presentity: the URI of the user whose feature status should
       be updated
     * feature: The name of the feature to update. Takes one of
       the following values:
          + DoNotDisturb
          + CallForwardingAlways
          + CallForwardingBusy
          + CallForwardingNoAnswer
     * status: the new status of the feature: 0 - disabled, 1 -
       enabled
     * route_param: optional string parameter passed to the
       $dfks(param) variable in set_route.
     * values: an array of extra values that can be updated for a
       feature. The format of an array element is: field/value.
       Supported fields are:
          + forwardTo - for all forwarding types
          + ringCount - for CallForwardingNoAnswer

   MI FIFO Command Format:
opensips-cli -x mi dfks_set_feature sip:alice@10.0.0.11 CallForwardingNo
Answer 1 1 \
ringCount/4 forwardTo/sip:bob@10.0.0.11

1.6. Exported Pseudo-Variables

1.6.1.  $dfks(field)

   This pseudo-variable can be used in the routes triggered by the
   module to handle the feature information through the following
   subnames:
     * assigned - inform the SIP phone that a feature is
       unassigned by setting this to 0 (the NOTIFY response will
       contain no XML data for the corresponding feature) By
       default, features are assigned.
     * notify - suppress the sending of the NOTIFY message by
       setting this to 0. By default, the NOTIFY is sent.
     * presentity - read-only, returns the current presentity URI.
     * feature - read-only, returns the current feature name.
       Possible values are:
          + DoNotDisturb
          + CallForwardingAlways
          + CallForwardingBusy
          + CallForwardingNoAnswer
     * status - read or write the feature status. A value of 1
       means enabled and 0 disabled.
     * param - returns the parameter passed by the
       mi_dfks_set_feature MI function. This field will be NULL if
       the parameter was not specified, or if the set_route is not
       triggered by an MI command, but by SIP signalling.
     * value/field - read or write extra feature values. field can
       be one of:
          + forwardTo - for all forwarding types
          + ringCount - for CallForwardingNoAnswer

   Example 1.3. dfks usage
...
route[dfks_set] {
    # CallForwardingAlways is not allowed
    if ($dfks(feature) == "CallForwardingAlways")
        $dfks(status) = 0;

    xlog("New status: $dfks(status) for feature '$dfks(feature)' of user
 '$dfks(presentity)'\n");
}
route[dfks_get] {
    if ($dfks(feature) == "CallForwardingNoAnswer") {
        $dfks(status) = 1;
        $dfks(value/forwardTo) = "sip:bob@10.0.0.11";
        $dfks(value/ringCount) = "3";
    } else if ($dfks(feature) == "CallForwardingAlways")
        $dfks(assigned) = 0;
    } else {
        ...
    }
}
...

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. Vlad Patrascu (@rvlad-patrascu) 23 7 1641 92
   2. Maksym Sobolyev (@sobomax) 8 6 16 21
   3. Bogdan-Andrei Iancu (@bogdan-iancu) 6 4 31 26
   4. Liviu Chircu (@liviuchircu) 4 2 2 2
   5. Razvan Crainea (@razvancrainea) 3 1 67 21

   (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. Bogdan-Andrei Iancu (@bogdan-iancu) Dec 2020 - Jan 2024
   2. Maksym Sobolyev (@sobomax)          Jan 2021 - Nov 2023
   3. Liviu Chircu (@liviuchircu)         Nov 2020 - Jan 2021
   4. Vlad Patrascu (@rvlad-patrascu)     Dec 2019 - Sep 2020
   5. Razvan Crainea (@razvancrainea)     Feb 2020 - Feb 2020

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

Chapter 3. Documentation

3.1. Contributors

   Last edited by: Bogdan-Andrei Iancu (@bogdan-iancu), Vlad
   Patrascu (@rvlad-patrascu), Razvan Crainea (@razvancrainea).

   Documentation Copyrights:

   Copyright © 2019 www.opensips-solutions.com
