# 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][dbuserror]. ``` // 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][dbuserror]. ``` // 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')); } }); ``` [dbuserror]: https://dbus.freedesktop.org/doc/api/html/group__DBusProtocol.html#gabb62fd6340d0787fbd56ff8dd2f326c7