Nemo QML Plugin D-Bus

API Documentation

DBusInterface QML Type

Provides access to a service on D-Bus More...

Import Statement: import Nemo.DBus 2.0

List of all members, including inherited members

Properties

bus : enum
iface : string
path : string
propertiesEnabled : bool
service : string
signalsEnabled : bool
status : enumeration
watchServiceStatus : bool

Signals

propertiesChanged()

Methods

void call(string method, var arguments, var callback, var errorCallback)
var getProperty(string name)
void setProperty(string name, var value)
bool typedCall(string method, var arguments, var callback, var errorCallback)

Detailed Description

The DBusInterface object can be used to call methods of objects on the system and session bus, as well as receive signals (see signalsEnabled) and read properties of those objects.

DBusInterface is intended to provide access to simple objects exposed over D-Bus. Property values and method arguments are automatically converted between QML/JS and D-Bus. There is limited control over this process. For more complex use cases it is recommended to use C++ and the Qt DBus module.

Handling D-Bus Signals

If signalsEnabled is set to true, signals of the destination object will be connected to functions on the object that have the same name.

Imagine a D-Bus object in service org.example.service at path /org/example/service and interface org.example.intf with two signals, UpdateAll and UpdateOne. You can handle these signals this way:

 DBusInterface {
     service: 'org.example.service'
     path: '/org/example/service'
     iface: 'org.example.intf'

     signalsEnabled: true

     function updateAll() {
         // Will be called when the "UpdateAll" signal is received
     }

     function updateOne(a, b) {
         // Will be called when the "UpdateOne" signal is received
     }
 }

Note: In D-Bus, signal names usually start with an uppercase letter, but in QML, function names on objects must start with lowercase letters. The plugin connects uppercase signal names to functions where the first letter is lowercase (the D-Bus signal UpdateOne is handled by the QML/JavaScript function updateOne).

Handling D-Bus Properties

If propertiesEnabled is set to true, properties of the destination object will be available on the local object with matching names.

 DBusInterface {
     service: 'org.example.service'
     path: '/org/example/service'
     iface: 'org.example.intf'

     propertiesEnabled: true

     property string activeState
     onActiveStateChanged: {
         // handle state change
     }
 }

Calling D-Bus Methods

Remote D-Bus methods can be called using either call() or typedCall(). call() provides a simpler calling API, only supporting basic data types, typedCall() supports more data types. Both methods provide callbacks for response and error handling.

Imagine a D-Bus object in service org.example.service at path /org/example/service and interface org.example.intf with two methods:

RegisterObject with a single object path parameter and returning a bool
Update with no parameters

You can call these two methods this way:

 DBusInterface {
     service: 'org.example.service'
     path: '/org/example/service'
     iface: 'org.example.intf'

     // Local function to call remote method RegisterObject
     function registerObject(object) {
         typedCall('RegisterObject',
                   { 'type': 'o', 'value': '/example/object/path' },
                   function(result) { console.log('call completed with:', result) },
                   function(error, message) { console.log('call failed', error, 'message:', message) })
     }

     // Location function to call remote method Update
     function update() {
         call('Update', undefined)
     }
 }

Property Documentation

bus : enum

This property holds whether to use the session or system D-Bus.

DBus.SessionBus - The D-Bus session bus
DBus.SystemBus - The D-Bus system bus

iface : string

This property holds the interface.

path : string

This property holds the object path of the object to access.

propertiesEnabled : bool

This property holds whether this object tracks properties on the remote D-Bus object. See Handling D-Bus Properties.

service : string

This property holds the service name of the service to connect to.

signalsEnabled : bool

This property holds whether this object listens signal emissions on the remote D-Bus object. See Handling D-Bus Signals.

status : enumeration

Returns the availability of the service if tracking is enabled via watchServiceStatus. Value can be:

DeclarativeDBusInterface.Unknown
DeclarativeDBusInterface.Unavailable
DeclarativeDBusInterface.Available

watchServiceStatus : bool

When enabled, the status property will match the current availability of the D-Bus service.

Signal Documentation

propertiesChanged()

This signal is emitted when properties of the D-Bus object have changed (only if the D-Bus object does emit signals when properties change). Right now, this does not tell which properties have changed and to which values.

This QML signal was introduced in version 2.0.8.

Method Documentation

void call(string method, var arguments, var callback, var errorCallback)

Call a D-Bus method with the name method on the object with arguments as either a single value or an array. For a function with no arguments, pass in undefined.

The callback arguments are handled as described under typedCall().

Note: This function supports passing basic data types and will fail if the signature of the remote method does not match the signature determined from the type of arguments. The typedCall() function can be used to explicity specify the type of each element of arguments.

var getProperty(string name)

Returns the the D-Bus property named name from the object.

void setProperty(string name, var value)

Sets the D-Bus property named name on the object to value.

This QML method was introduced in version 2.0.0.

bool typedCall(string method, var arguments, var callback, var errorCallback)

Call a D-Bus method with the name method on the object with arguments. Each parameter is described by an object:

 {
     'type': 'o'
     'value': '/org/example'
 }

Where type is the D-Bus type that value should be marshalled as. arguments can be either a single object describing the parameter or an array of objects.

A method with the D-Bus signature ssa{sv}, so two string parameters and an array of dict can be called like this:

 typedCall("setInventory", [
     { "type" : 's', "value": "apple" },
     { "type" : 's', "value": "banana" },
     { "type" : 'a{sv}',
       "value": [ { "name": "rose", "color": "red", "hasThorns": true, "count": 3 } ],
     },
 ])

When the function returns, callback is called with the method reply message as a single argument. If the function fails, errorCallback is called with two parameters, the error name (e.g. org.freedesktop.DBus.Error.InvalidArgs) and the error message ("Failed to create method call (Invalid argument)").

Both callback arguments are optional, if set to undefined (the default), the return value and/or error messages will be discarded.