DBus Remote API

Starting with version v0.9.7-beta.3 (not corresponding to a packaged release though) When has gained a remote API through DBus. This API can be used to control various aspects of a running instance of When, so that it can even be almost completely managed by an external application. Operations available through the remote API cover:

  • managing all types of items: tasks, conditions and signal handlers
  • managing the configuration and configuration file
  • pausing or resetting a running instance
  • retrieving current history

and more. This interface has been created to allow development of a companion application, the upcoming When Wizard, that will provide a different and easier way to manage When letting it only perform as a mere engine.

When exposes methods that are somehow reserved for itself (mainly the ones that allow communication between the command line utility and a running applet instance), and also methods that are available for external control. This section only briefly documents the former ones, while trying to be more extensive with the latter type.


Details on how to estabilish DBus a connection to the When applet follow:

Item Value
Bus session
Application ID it.jks.WhenCommand
Unique Bus ID it.jks.WhenCommand.BusService
Object Path /it/jks/WhenCommand/BusService
Interface it.jks.WhenCommand.BusService

These values can be used to build a proxy to the When interface, see the DBus documentation for more details. Specifically, to build a proxy in Python the following model can be used:

import dbus

bus = dbus.SessionBus()
proxy = bus.get_object('it.jks.WhenCommand.BusService',

It will give access to the whole API in the form proxy.call(p1[, p2 ...]) where call is the name of an API method (see below) and pN are the parameters expected by the method.

General Use Methods

The following methods have been designed aiming at interoperability, thus they are useful for the purposes explained above.

Method Description
AddItemByDefinition(dic, save) add an item to the collection of items managed by When, and optionally save the collection where the item belongs. The item must be provided in dictionary form, as specified below, in the dic parameter, while the save argument is a boolean indicating whether or not to save the collection; returns True on success, False ortherwise [1]
AddItemsBatch(item_data) add multiple items using a string in the item definition file format (see the user guide for detailed information); the argument should follow the format exactly, with newlines, indents and so on; returns True on success, False ortherwise
GetConfig(section, entry) return a value (enclosed in a variant) from the running configuration, which in turn most likely reflects the same value in the configuration file; section and entry are strings [2]
GetHistoryEntries() return the list of entries in thehistory of the running instance: the entries are returned as a list of strings, corresponding each to a line of an exported history file – except for headers – that is a semicolon separated list of values
GetItemDefinition(item_spec) given an item specification [3] as argument, return the definition of the corresponding item as a mapping (dictionary) if it exists [1]
GetItemNames(item_type) return a list of item names possibly corresponding to the specified type of item if the item_type parameter is one of 'tasks', 'conditions' and 'sighandlers' (or an abbreviation thereof), or all items if the empty string is passed
IsSuspendedCondition(cond_name) tell whether or not the condition whose name is provided as argument is suspended
Pause(pause) set the paused state to the one provided in the boolean pause argument: paused if True, resumed if False
Paused() return the current paused state as a self-explanatory boolean value
ReloadConfig() reconfigure the applet from static data
RestartConditions() reset the internal flag of conditions that avoids to repeat checks if one test had already been successful, thus reenabling non-recurring conditions
RemoveItem(item_spec) given an item specification [3] remove the corresponding item; returns True on success, False ortherwise
Reset(clear_history) reset the applet and reload data, similar to a restart but without running startup and shutdown actions; if the clear_history parameter is set to True also clear the current task history
SaveItems(item_type) save all items of the type provided in item_type (see GetItemNames above on how to specify it), all items are saved when providing the empty string
SetConfig(sec, ent, v, reload) set the configuration entry ent at section sec in the running applet to the value specified in v (which must be provided as a variant); if the boolean argument reload is set to True the configuration is reloaded after the operation; returns True on success and False on failure
SuspendCondition(cond_name, s) if s is True the condition is suspended, if False it is resumed

Item definition dictionaries returned by GetItemDefinition and handled by AddItemByDefinition are implemented using strings as keys and variants as values.

Reserved Methods

Methods that should be avoided generally are: ExportHistory that exports history entries to a file given its name, KillInstance and QuitInstance (especiatlly the former) that causes the applet to exit, RunCLIBasedCondition that is only used to force a command-line based condition to occur and ShowDialog to fire up a dialog box. These methods are only used with when-command as a controlling utility, and are pretty useless in external applications.

[1](1, 2) the DBus documentation explains how to access DBus dictionaries; in this particular case the keys are strings and values must be enclosed in variant objects.
[2]sometimes When expects data to be enclosed in a variant container: there are several methods to achieve this, including the use of the GLib.Variant (GLib::Variant) constructor.
[3](1, 2) a string consisting of the tipe of item (or an abbreviation thereof) in tasks, conditions, and sighandlers, following by a colon and the unique name of the item itself. For example, if there is a task named SomeTask, then task:SomeTask is a correct item specification (where task is actually an abbreviation of the more general tasks).