Api - fpaut/cloudeebus GitHub Wiki
Javascript objects and interfaces
Following is a brief description of the cloudeebus Javascript objects and their methods. This API is designed to be somewhat similar to the higher level dbus-python APIs. All asynchronous methods take optional success and error callbacks.
cloudeebus Object
There is one global instance of the cloudeebus object created when cloudeebus.js is loaded.
It manages the initial connection to the server, and holds the Session and System bus connection.
Attributes
version : current version of the Javascript library
minVersion : minimum supported version of the Python server
Methods
cloudeebus.connect(uri, manifest, successCB, errorCB)
Connection to the cloudeebus.py server. Returns nothing.
uri : websocket uri, for instance ws://localhost:9000
manifest : A json manifest. See the "managing security" section for an example. When server runs in --opendoor mode, pass null.
successCB : callback fired when connection succeeds, takes no argument.
errorCB : callback fired when connection fails, takes error message string for argument.
cloudeebus.SessionBus()
Returns a cloudeebus.BusConnection object holding a connection to the Session bus.
cloudeebus.SystemBus()
Returns a cloudeebus.BusConnection object holding a connection to the System bus.
cloudeebus.log(message)
Does nothing. Replace by your custom method to display internal error messages, for instance:
cloudeebus.log = function(msg) {
alert(msg);
}
cloudeebus.BusConnection Interface
A BusConnection object holds a connection to the Session bus or the System bus, for instance:
var bus = cloudeebus.SessionBus();
Methods
getObject(busName, objectPath, introspectCB, errorCB)
Returns a cloudeebus.ProxyObject object that can call DBus methods and be registered for DBus signals.
busName : DBus service, for instance org.gnome.ScreenSaver
objectPath : Object for which to get the proxy, for instance /
introspectCB : Optional callback. If passed, the object is introspected, i.e. populated with its methods and attributes and passed to the callback as argument.
errorCB : Optional callback fired on introspection error, takes error message string for argument.
cloudeebus.ProxyObject Interface
A ProxyObject is a proxy to a remote DBus objects, with its methods and attributes, for instance:
var obj = bus.getObject("org.gnome.ScreenSaver", "/");
Attributes
busName : DBus service for this object.
objectPath : DBus path for this object.
interfaceProxies : Dictionary of cloudeebus.ProxyObject objects indexed by interfaces.
If the object is introspected, i.e. if a introspectCB callback was passed to bus.getObject, then it also has the DBus Properties of the remote object as attributes.
Methods
callMethod(ifName, method, args, signature)
Calls a DBus method on the proxy object. Returns a cloudeebus.Promise object.
ifName : Interface name, for instance org.gnome.ScreenSaver
method : Name of the method to call, for instance SetActive
args : Argument list for the method, for instance [true]
signature : Optional DBus signature for the method, for instance "b"
If the object is introspected then the method can be called directly by its name, for instance in the example above:
obj.SetActive(true)
instead of:
obj.callMethod("org.gnome.ScreenSaver", "SetActive", [true], "b")
getInterface(ifName)
Use on introspected objects. Returns a version of this cloudeebus.ProxyObject with only attributes and methods of interface which name is passed as parameter. This is useful if the object implements interfaces with conflicting method or attribute names.
ifName : Interface name, for instance org.gnome.ScreenSaver
Interface objects are stored in the interfaceProxies dictionary. Iterate on the dictionary to get interfaces name.
connectToSignal(ifName, signal, handlerCB, errorCB)
Connects the proxy object to a DBus signal. Returns nothing.
ifName : Interface name, for instance org.gnome.ScreenSaver
signal : Name of the signal to register for, for instance ActiveChanged
handlerCB : Signal handler callback, fired when the signal is emitted. Takes the dbus signal data for arguments.
errorCB : Optional callback fired on error, takes error message string for argument.
disconnectSignal(ifName, signal)
Disconnects the proxy object from a DBus signal. Returns nothing.
ifName : Interface name, for instance org.gnome.ScreenSaver
signal : Name of the signal to register for, for instance ActiveChanged
cloudeebus.Promise Interface
This is an implementation of the DOMPromise interface returned by cloudeebus.ProxyObject.callMethod. The then method can be used to set callbacks right on an asynchronous call result, for instance:
obj.SetActive(true).then(successCB, errorCB);
is equivalent to:
var promise = obj.SetActive(true);
promise.then(successCB, errorCB);
Attributes
state : "pending", "fulfilled" or "rejected"
result : method result if fulfilled, error message if rejected
Constructor
cloudeebus.Promise(function(resolver){})
The cloudeebus.Promise constructor takes a callback as parameter, the argument of which is a cloudeebus.PromiseResolver.
Methods
then(fulfillCallback, rejectCallback)
Appends callbacks to the current cloudeebus.Promise object. Returns a new cloudeebus.Promise object in the context of which the callbacks will be executed.
fulfillCallback : optional callback fired when the cloudeebus method succeeds. Arguments depends on method.
rejectCallback : optional callback fired when the cloudeebus method fails, takes error message string for argument.
catch(rejectCallback)
Identical to invoking promise.then(undefined, rejectCallback).
rejectCallback : optional callback fired when the cloudeebus method fails, takes error message string for argument.
done(fulfillCallback, rejectCallback)
Appends callbacks to the current cloudeebus.Promise object. Returns nothing.
fulfillCallback : optional callback fired when the cloudeebus method succeeds. Arguments depends on method.
rejectCallback : optional callback fired when the cloudeebus method fails, takes error message string for argument.
Static Methods
cloudeebus.Promise.fulfill(value)
Returns a new cloudeebus.Promise object that is fulfilled with result value.
value : any value.
cloudeebus.Promise.resolve(value)
Returns a new cloudeebus.Promise object that is fulfilled or rejected depending upon value.
value : any value.
cloudeebus.Promise.reject(value)
Returns a new cloudeebus.Promise object that is rejected with result value.
value : any value.
cloudeebus.Promise.any(values)
Returns a new cloudeebus.Promise object that is fulfilled or rejected when any value is either fulfilled or rejected.
values : variable number of arguments containing any value.
cloudeebus.Promise.every(values)
Returns a new cloudeebus.Promise object that is fulfilled or rejected when all values are fulfilled or any is rejected.
values : variable number of arguments containing any value.
cloudeebus.Promise.some(values)
Returns a new cloudeebus.Promise object that is fulfilled or rejected when any value is fulfilled or all are rejected.
values : variable number of arguments containing any value.
cloudeebus.PromiseResolver Interface
Attributes
resolved : flag. Set when one of the fulfill, resolve, or reject methods is completed.
Methods
fulfill(value)
Associated cloudeebus.Promise object is fulfilled with result value.
value : any value.
resolve(value)
Associated cloudeebus.Promise object is fulfilled or rejected depending upon value.
value : any value.
reject(value)
Associated cloudeebus.Promise object is rejected with result value.
value : any value.
Example
The following example locks the screen. No manifest is passed, so the server must be executed in --opendoor mode, for instance:
cloudeebus.py --debug --opendoor --port=9001
The Javascript code connects to cloudeebus without a manifest, gets an introspected proxy for the screen saver root object on the session bus, and locks the screen. The success/error callbacks are setted with the method 'then' from the DOMPromise interface.
function connectSuccess() {
var bus = cloudeebus.SessionBus();
bus.getObject("org.gnome.ScreenSaver", "/", lock);
}
function lockSuccess() {
cloudeebus.log('Device successfully locked');
}
function lockFail(error) {
cloudeebus.log('Lock fails!');
}
function lock(proxy) {
proxy.SetActive(true).then(lockSuccess, lockFail);
}
cloudeebus.connect("ws://localhost:9001", null, connectSuccess);