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 CallForwardingNoAnswer 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)

 NameDevScoreCommitsLines ++Lines --
1. Vlad Patrascu (@rvlad-patrascu)237164192
2. Maksym Sobolyev (@sobomax)861621
3. Bogdan-Andrei Iancu (@bogdan-iancu)643126
4. Liviu Chircu (@liviuchircu)4222
5. Razvan Crainea (@razvancrainea)316721

(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

 NameCommit 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