-
Notifications
You must be signed in to change notification settings - Fork 16
Api
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 return a DOMPromise object.
-
cloudeebusObject -
cloudeebus.BusConnectionInterface -
cloudeebus.ProxyObjectInterface -
cloudeebus.ServiceInterface -
cloudeebus.AgentInterface -
cloudeebus.PromiseInterface -
cloudeebus.PromiseResolverInterface
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.
version : current version of the Javascript library
minVersion : minimum supported version of the Python server
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.
Returns a cloudeebus.BusConnection object holding a connection to the Session bus.
Returns a cloudeebus.BusConnection object holding a connection to the System bus.
Does nothing. Replace by your custom method to display internal error messages, for instance:
cloudeebus.log = function(msg) {
alert(msg);
}
A BusConnection object holds a connection to the Session bus or the System bus, for instance:
var bus = cloudeebus.SessionBus();
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.
Creates a DBus Named Service. Returns a cloudeebus.Promise object. The Promise's fulfillCallback argument is a new cloudeebus.Service object.
serviceName : requested DBus Named Service.
A ProxyObject is a proxy to a remote DBus objects, with its methods and attributes, for instance:
var obj = bus.getObject("org.gnome.ScreenSaver", "/");
busName : DBus service for this object.
objectPath : DBus path for this object.
interfaceProxies : Dictionary of cloudeebus.ProxyObject objects indexed by interfaces.
childNodeNames : Array of strings containing this object's children dbus pathes.
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.
Calls a DBus method on the proxy object. Returns a cloudeebus.Promise object. The Promise's fulfillCallback arguments are the method results.
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")
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.
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.
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
The object holding the DBus service.
Unregisters the DBus Named Service corresponding to the current cloudeebus.Service object. Returns a cloudeebus.Promise object.
Creates an agent attached to the current cloudeebus.Service object. Returns a cloudeebus.Promise object.
agent : the agent to add on the service.
Removes an agent from the current cloudeebus.Service object. Returns a cloudeebus.Promise object.
agent : the agent to remove from the service.
The object holding a cloudeebus agent.
objectPath : DBus path for this object.
handler : Javascript object implementing the interfaces, methods and signal emitters for this agent.
xml : interfaces definition in DBus introspection XML format.
The cloudeebus.Agent constructor.
objectPath : the agent's path on its DBus service.
handler : Javascript object implementing the interfaces/methods for this agent. If the handler object implements several interfaces with conflicting method names, it must also have an interfaceProxies dictionary. Methods to emit signals are automatically added to this handler object by the cloudeebus.Service.addAgent function, named as the corresponding signal.
xml : description of the interfaces/methods and signals this agent implements, in DBus introspection XML format.
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);
state : "pending", "fulfilled" or "rejected"
result : method result if fulfilled, error message if rejected
The cloudeebus.Promise constructor takes a callback as parameter, the argument of which is a cloudeebus.PromiseResolver.
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.
Identical to invoking promise.then(undefined, rejectCallback).
rejectCallback : optional callback fired when the cloudeebus method fails, takes error message string for argument.
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.
Returns a new cloudeebus.Promise object that is fulfilled with result value.
value : any value.
Returns a new cloudeebus.Promise object that is fulfilled or rejected depending upon value.
value : any value.
Returns a new cloudeebus.Promise object that is rejected with result value.
value : any value.
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.
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.
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.
resolved : flag. Set when one of the fulfill, resolve, or reject methods is completed.
Associated cloudeebus.Promise object is fulfilled with result value.
value : any value.
Associated cloudeebus.Promise object is fulfilled or rejected depending upon value.
value : any value.
Associated cloudeebus.Promise object is rejected with result value.
value : any value.
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() {
alert('Device successfully locked');
}
function lock(proxy) {
proxy.SetActive(true).then(lockSuccess, cloudeebus.log);
}
cloudeebus.connect("ws://localhost:9001", null, connectSuccess, alert);
In this example, one web page exports a DBus service, and another web page calls into it. Both pages connect to the same server, in --opendoor mode, for instance:
cloudeebus.py --debug --opendoor --port=9001
The following Javascript code exposes a DBus service that does additions.
var sampleXml= '<!DOCTYPE node PUBLIC "-//freedesktop//DTD D-BUS Object Introspection 1.0//EN"\n"http://www.freedesktop.org/standards/dbus/1.0/introspect.dtd">\n<node><interface name="org.cloudeebus.Sample"><method name="Add"><arg type="i" name="arg1"/><arg type="i" name="arg2"/><arg type="i" name="result" direction="out"/></method></interface></node>';
sampleObjectHandler = {
Add: function(a,b) {
return a+b;
}
};
function addAgent(service) {
var agent = new cloudeebus.Agent("/org/cloudeebus/Sample", sampleObjectHandler, sampleXml);
service.addAgent(agent);
}
function connectSuccess() {
cloudeebus.SessionBus().addService("org.cloudeebus.Sample").then(addAgent, cloudeebus.log);
}
cloudeebus.connect("ws://localhost:9001", null, connectSuccess, alert);
function connectSuccess() {
var bus = cloudeebus.SessionBus();
bus.getObject("org.cloudeebus.Sample", "/org/cloudeebus/Sample", callAdd);
}
function gotAddResult(result) {
alert("Got result: " + result);
}
function callAdd(proxy) {
proxy.Add(10,5).then(gotAddResult, cloudeebus.log);
}
cloudeebus.connect("ws://localhost:9001", null, connectSuccess, alert);