PRESENCE_DFKS module

Admin Guide

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

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.

Dependencies

OpenSIPS Modules

The following modules must be loaded before this module:

• presence.

External Libraries or Applications

• libxml2-dev.

Exported Parameters

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”.

Set parameter

...
modparam("presence_dfks", "get_route", "dfks_get")
...

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”.

Set parameter

...
modparam("presence_dfks", "set_route", "dfks_set")
...

Exported Functions

None.

Exported MI Functions

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

Exported Pseudo-Variables

$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

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 {
        ...
    }
}
...

Contributors

By Commit Statistics

Top contributors by DevScore⁽¹⁾, authored commits⁽²⁾ and lines added/removed⁽³⁾

#	Name	DevScore	Commits	Lines++	Lines—
1.	Vlad Patrascu (@rvlad-patrascu)	24	7	1667	118
2.	Stefan Darius (@dariusstefan)	10	5	283	71
3.	Maksym Sobolyev (@sobomax)	5	3	10	15
4.	Razvan Crainea (@razvancrainea)	4	2	69	23
5.	Bogdan-Andrei Iancu (@bogdan-iancu)	4	2	12	12
6.	Liviu Chircu (@liviuchircu)	4	2	2	2

(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

(3) ignoring whitespace edits, renamed files and auto-generated files

By Commit Activity

#	Name	Commit Activity
1.	Stefan Darius (@dariusstefan)	Jun 2026 - Jul 2026
2.	Razvan Crainea (@razvancrainea)	Feb 2020 - Jun 2026
3.	Bogdan-Andrei Iancu (@bogdan-iancu)	Dec 2020 - Jan 2024
4.	Maksym Sobolyev (@sobomax)	Jan 2021 - Jan 2021
5.	Liviu Chircu (@liviuchircu)	Nov 2020 - Jan 2021
6.	Vlad Patrascu (@rvlad-patrascu)	Dec 2019 - Sep 2020

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

Documentation

Contributors

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

License

All documentation files (i.e. .md extension) are licensed under the Creative Common License 4.0