TV Browser Javascript D-Bus API design

Javascript D-Bus API Overview

This document is a design of JavaScript D-Bus API for MeeGo TV browser

What does D-Bus API provide?

The D-Bus API provides interface to acces D-Bus service with Javascript language bindings. There are actually multiple D-Bus message buses running on MeeGo (and on your average Linux system) at any one time, of two types:

* The system bus is a machine-global, single instance of the daemon with security restrictions on what messages it will accept. It's used for system-wide communication and communication between the user desktop and the operating system.
* A session bus is created for each user session. It allows applications within that user session to communicate. Most MeeGo D-Bus services (connman etc.) communicate via the session bus.

To get system bus, use the following code snippet:

var system = dbuslib.system_bus();

To get session bus,

var session = dbuslib.session_bus();

The services, interfaces and objects

Interfaces are the contract between an object and its callers, much like interfaces in Java, GObject etc.. An interface, as in most object-oriented programming environments, defines the methods and properties an object exposes. In addition, D-Bus interfaces can also contain signals. Signals provide a way for objects to notify other objects about events which happen to them: for example, a Door interface might provide a signal to other objects when it is opened, perhaps called door-opened. (A nearby Doorman object might listen out for door-opened signals, so it knows when people come into the building.)

Each D-Bus object implements one or more interfaces. Most implement two standard interfaces as a minimum, org.freedesktop.DBus.Introspectable and org.freedesktop.DBus.Properties.

The following code gives an example of get interface object with given arguments

var iface = dbuslib.get_interface(session,      //the bus
                                 "org.freedesktop.compiz",   //the service name
                                 "/org/freedesktop/compiz",  //the object path
                                 "org.freedesktop.compiz");  //the interface

The returned interface also retrieves the method and signal interfaces

The method call

The call message will contain any arguments to the method. The reply message may indicate an error, or may contain data returned by the method.

var return_value = iface.GetPlugins();
console.log(return_value);

The signal emitting

A signal in DBus consists of a single message, sent by one process to any number of other processes.

iface.pluginChanged.onemit = funcion() {
   console.log("plugin changed callback");
}

The sample code

The following is the full sample code

var session = dbuslib.session_bus();
var iface = dbuslib.get_interface(session,      //the bus
                                 "org.freedesktop.compiz",   //the service name
                                 "/org/freedesktop/compiz",  //the object path
                                 "org.freedesktop.compiz");  //the interface

var return_value = iface.GetPlugins();
console.log(return_value);

iface.pluginChanged.onemit = funcion() {
   console.log("plugin changed callback");
}