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
service : string
signalsEnabled : bool

Signals

propertiesChanged()

Methods

void call(string method, variant arguments, variant callback, variant errorCallback)
void setProperty(string name, variant value)
bool typedCall(string method, variant arguments, variant callback, variant 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).

Calling D-Bus Methods

Remote D-Bus methods can be called using either call() or typedCall(). call() provides a simplier calling API, only supporting basic data types and discards any value return by the method. typedCall() supports more data types and has callbacks for call completion and error.

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.

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.

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, variant arguments, variant callback, variant 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.

When the function returns, call callback with a single argument that is the return value. The callback argument is optional, if set to undefined (the default), the return value will be discarded. If the function fails errorCallback is called if it is not set to undefined (the default).

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.

void setProperty(string name, variant 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, variant arguments, variant callback, variant 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.