Skip to content

Latest commit

 

History

History
237 lines (179 loc) · 4.61 KB

MIGRATING.md

File metadata and controls

237 lines (179 loc) · 4.61 KB
Raw

Migrating

Many core APIs changed betwen v0.2.21 and v1.0.0. This document describes how to upgrade your application or library to use the new APIs when upgrading to dbus 1.0.0.

Clients

Migrating node applications and libraries that use this module as a DBus client.

Getting a bus

In version 1.0.0, you no longer need to instantiate an instance of DBus in order to get a Bus instance.

v0.2.21:

// v0.2.21
var DBus = require('dbus');
var dbus = new DBus();
var bus = dbus.getBus('session');

v1.0.0:

// v1.0.0
var DBus = require('dbus');
var bus = DBus.getBus('session');

Calling a method

In version 1.0.0, calling a method on a DBus service uses a common node callback pattern where the first parameter is an error and the second is the result.

v0.2.21:

// v0.2.21
interface.Add.timeout = 1000;
interface.Add.error = function(err) {
  // handle error
};
interface.Add.finish = function(result) {
  assert(result === 3);
};
interface.Add(1, 2);

v1.0.0:

// v1.0.0
interface.Add(1, 2, { timeout: 1000 }, function(err, result) {
  if (err) {
    // handle error
  }

  assert(result === 3);
});

Timeout may be omitted if it is not needed.

// v1.0.0
interface.Add(1, 2, function(err, result) {
  if (err) {
    // handle error
  }

  assert(result === 3);
});

Services

Migrating node applications and libraries that use this module to create DBus services.

Creating a service

In version 1.0.0, you no longer need to instantiate an instance of DBus in order to get a Service instance.

v0.2.21:

// v0.2.21
var DBus = require('dbus');
var dbus = new DBus();
var service = dbus.registerService('session', 'test.dbus.TestService');

v1.0.0:

// v1.0.0
var DBus = require('dbus');
var service = DBus.registerService('session', 'test.dbus.TestService');

Responding to a method

In v1.0.0, methods use a more typical node callback pattern where an error is the first parameter and a result is the second parameter.

v0.2.21:

// v0.2.21
service.addMethod('MyMethod', { out: DBus.Define(Number) }, function(callback) {
  callback(3);
});

v1.0.0:

// v1.0.0
service.addMethod('MyMethod', { out: DBus.Define(Number) }, function(callback) {
  callback(null, 3); // return the result as the second parameter
});

Throwing an error from a method

In v1.0.0, errors can include both the DBus name and a message. Previously, they could only include the DBus name.

v0.2.21:

// v0.2.21
service.addMethod('MyMethod', { out: DBus.Define(Number) }, function(callback) {
  callback(new Error('test.dbus.TestService.Error');
});

v1.0.0:

// v1.0.0
service.addMethod('MyMethod', { out: DBus.Define(Number) }, function(callback) {
  callback(new DBus.Error('test.dbus.TestService.Error', 'Human-readable error message'));
});

Using a standard error is still possible, and defaults to DBUS_ERROR_FAILED.

// v1.0.0
service.addMethod('MyMethod', { out: DBus.Define(Number) }, function(callback) {
  // Error name defaults to the generic 'org.freedesktop.DBus.Error.Failed'
  callback(new Error('Human-readable error message')); 
});

Responding to a property

In v1.0.0, properties use a more typical node callback pattern where an error is the first parameter and a result is the second parameter.

v0.2.21:

// v0.2.21
service.addProperty('MyProperty', {
  type: DBus.Define(Number),
  getter: function(callback) {
    callback(3);
  }
});

v1.0.0:

// v1.0.0
service.addProperty('MyProperty', {
  type: DBus.Define(Number),
  getter: function(callback) {
    callback(null, 3); // Return the result as the second parameter.
  }
});

Throwing an error from a property

In v1.0.0, errors can include both the DBus name and a message. Previously, they could only include the DBus name.

v0.2.21:

// v0.2.21
service.addProperty('MyProperty', { 
  type: DBus.Define(Number),
  getter: function(callback) {
    callback(new Error('test.dbus.TestService.Error');
  }
});

v1.0.0:

// v1.0.0
service.addProperty('MyProperty', {
  type: DBus.Define(Number),
  getter: function(callback) {
    callback(new DBus.Error('test.dbus.TestService.Error', 'Human-readable error message'));
  }
});

Using a standard error is still possible, and defaults to DBUS_ERROR_FAILED.

// v1.0.0
service.addProperty('MyProperty', {
  type: DBus.Define(Number),
  getter: function(callback) {
    // Error name defaults to the generic 'org.freedesktop.DBus.Error.Failed'
    callback(new Error('Human-readable error message')); 
  }
});