cockpit.js: DBus Client

Cockpit allows access to DBus services via this API.

DBus Types

DBus values are represented as javascript values and objects as follows:

+BYTE 'y'+: Javascript number.
+BOOLEAN 'b'+: Javascript boolean.
+INT16 'n'+: Javascript number.
+UINT16 'q'+: Javascript number.
+INT32 'i'+: Javascript number.
+UINT32 'u'+: Javascript number.
+INT64 'x'+: Javascript number.
+UINT64 't'+: Javascript number.
+DOUBLE 'd'+: Javascript number.
+STRING 's'+: Javascript string.
+OBJECT_PATH 'o'+: Javascript string.
+SIGNATURE 'g'+: Javascript string.
+ARRAY of BYTE 'ay'+: A string containing base64 encoded data.
+ARRAY of DICT_ENTRY with STRING keys 'a{s?}'+: A javascript plain object with the keys as property names.
+ARRAY of DICT_ENTRY with other keys 'a{??}'+: A javascript plain object each key JSON encoded into a string property name.
+ARRAY of other+: A javascript array.
+VARIANT+: A javascript plain object with the +"t"+ property set to a DBus type string, and the +"v"+ property set to a value.
+HANDLE 'h'+: A javascript object that describes a cockpit channel which represents the passed file descriptor. The +payload+ is always set to +stream+. Pass it to cockpit.channel() to create the channel and start reading or writing on it. Handles can only be received, not sent from within cockpit.

cockpit.dbus()

client = cockpit.dbus(name, [options])

Create a DBus client for the given bus +name+ (eg: service name). Use the following functions to make DBus method calls, watch for events, etc. The optional +options+ argument is a javascript plain object, and may include:

+"bus"+: The DBus bus to connect to. Specifying +"session"+ will connect to the DBus user session bus, +"user"+ will connect to the user bus (on some systems this is identical to the session bus), +"system"+ will connect to the DBus system bus, and +"none"+ to the non-standard bus specified with the +address+ option. This defaults to "system" if not present.
+"address"+: The bus address to connect to in case +bus+ is +"none"+.
+"superuser"+: Set to +"require"+ to talk to this service as root. The DBus service will see the DBus method calls and accesses as coming from root, rather than the logged in user. This is useful for talking to services that do not correctly use polkit to authorize administrative users. If the currently logged in user is not permitted to become root (eg: via +pkexec+) then the +client+ will immediately be closed with a +"access-denied"+ problem code.
Set to +"try"+ to try to talk as root, but if that fails, fall back to unprivileged.
+"track"+: It is valid for a DBus service to exit, and be restarted in such a way that clients continue to talk to it across the restart. Some services are not written with this in mind. If the +"track"+ option is set to +true+ then the channel will close when the service exits and/or disconnects from the DBus bus.

If the +name+ argument is null, and no options other than +"bus"+ are specified, then a shared DBus +client+ is created. When using such a client with a DBus bus, a +"name"+ option must be specified on various other methods in order to specify which client to talk to.

client.wait()

promise = client.wait([callback])

Returns a +promise+ that is ready when the client is ready, or fails if the client closes. If a +callback+ is specified, it is attached to the promise.

client.close()

client.close([problem])

Close the DBus client. If +problem+ is specified it should be a problem code string.

client.onclose

client.addEventListener("close", options => { ... })

An event triggered when the DBus client closes. This can happen either because client.close() function was called, or the DBus service went away, or some other problem or disconnection.

The +options+ will contain various close information, including a +"problem"+ field which will be set if the channel was closed because of a problem.

client.onowner

client.addEventListener("owner", (event, owner) => { ... })

An event triggered when the owner of the DBus name changes. The owner value will be the id of the name owner on the bus or null if the name is unowned. The absence of an owner should not be treated as a disconnection. However this makes it possible to take some action based on the actual status of the service, for example disconnecting a pending signal handler.

client.options

Set to the options used when creating the client. Will not change for the life of the client.

client.unique_name

The unique DBus name of the client. Initially null, and becomes valid once the the client is ready.

client.proxy()

proxy = client.proxy([interface, path], [options])

Create proxy javascript object for a DBus +interface+. At the specified DBus object +path+. The proxy will have properties, methods and signals from to the DBus interface, and allows for natural interaction. If no +interface+ is specified then the DBus bus name of the client is used. If no +path+ is specified, then the DBus name of the client is converted to a path.

If creating lots of proxies for a given +interface+ it is more efficient to use the +client.proxies()+ function.

The proxy is loaded when the +proxy.valid+ field is +true+, and it is set to +false+ if the underlying +interface+ and/or +path+ don’t or no longer exist, or the +client+ has closed. You can wait for proxy to become valid by passing a callback to its +proxy.wait()+ function. The +proxy.onchanged+ event will also fire when the proxy becomes valid or invalid. DBus properties and methods on the proxy are not defined until the proxy becomes valid.

value = proxy.Prop1
proxy.WritableProp = value

All DBus properties on the +interface+ that start with an upper case letter (as is convention) will be automatically defined on this proxy, and will update their values as the DBus property values change. In addition the +proxy.onchanged+ event will fire every time the properties change.

If you assign a value to a writable property on the proxy, the proxy will try to set that property on the DBus +interface+ at +path+. The actual proxy property value will not update until the DBus service has notified the proxy of the change. If setting a property fails a warning will be logged. In order to have more reliable setting of properties, or track when they have been set, or if setting fails, use the +client.call()+ directly. It should be noted that DBus service implementations may also be inconsistent in their behavior when setting a property fails.

You can access the raw property data using the +proxy.data+ field, including data for properties that do not start with an upper case letter.

proxy.Method(arg1, arg2)
    .then((retval1, retval2) => {
        ...
    })
    .catch(ex => {
        ...
    });

All DBus methods on the +interface+ that start with an upper case letter (as is convention) will be automatically defined on this proxy. These methods are called with arguments as normal javascript arguments. A Promise that will complete successfully when the method returns, or fail if an error occurs. The return values from the DBus method will be passed to the +then+ handler function directly.

Methods that do not start with an upper case letter can be invoked by using the usual +proxy.call()+ directly.

proxy.addEventListener("Signal", (event, arg1, arg2) => {
    ...
});

All DBus signals on the +interface+ that start with an upper case letter (as is convention) will be automatically emit events on this proxy. These events will contain the signal arguments after the standard +event+ argument.

Signals that do not start with an upper case letter can be subscribed to by using +proxy.onsignal+ directly.

Usually a proxy asks the +client+ to watch and notify it of changes to the relevant object or path. You can pass an +options+ argument with the +watch+ field set to +false+ to prevent this.

proxy.client

Set to the DBus client of the proxy. Will not change for the life of the proxy.

proxy.path

Set to the DBus object path of the proxy. Will not change for the life of the proxy.

proxy.iface

Set to the DBus interface name of the proxy. Will not change for the life of the proxy.

proxy.valid

Set to +true+ when the proxy’s DBus interface is present at its DBus path, and all information for the proxy has loaded. Is set to +false+ while loading, and after the proxy no longer refers a DBus interface and path. Also set to +false+ if the +client+ closes.

Use the by +proxy.wait()+ function to wait for a proxy to load. The +proxy.onchanged+ event will also be emitted when the proxy becomes valid or invalid. DBus properties and methods on the proxy are not defined until the proxy becomes valid.

proxy.data

A plain javascript object containing all the raw property data that this proxy has loaded. This will be updated automatically as the proxy is notified of property changes from the DBus service. The +proxy.onchanged+ event will be emitted when it changes.

proxy.call()

invocation = proxy.call(method, args, [options])

Make a DBus method call on this proxy.

For DBus methods that start with an upper case letter, is usually more convenient to call the method directly on the proxy. However if methods that do not follow the usual DBus convention, or specify additional options, or the caller cannot be sure that the method actually exists, you can use this method.

This function also works on proxies that have are still loading and have not become valid yet.

The +method+ should be a DBus method name, and the +args+ should be an array of arguments to pass to the method. The +options+ are described elsewhere.

The returned value is identical to the one returned from client.call(). It is a Promise that will complete successfully when the method returns, or fail if an error occurs.

proxy.wait()

promise = proxy.wait()
proxy.wait(() => {
    ...
});

Wait for a proxy to finish loading. This function returns a promise. If a callback function is passed as an argument then that function will be invoked when the proxy is ready. If this method is called after a proxy has already loaded, then the promise will be resolved immediately, and any callback will be invoked immediately. Use the promise or +proxy.valid+ to determine whether the proxy is valid.

proxy.onchanged

proxy.addEventListener("changed", (event, data) => {
    ...
});

This event is emitted when the proxy’s properties change.

The +data+ has the following form, and will only include properties that have changed:

{
    "Prop1": "value",
    "Prop2": 5
}

proxy.onsignal

proxy.addEventListener("signal", (event, name, args) => {
    ...
});

This event is emitted when the proxy’s emits an event.

For most events, that have names which start with an upper case letter, you can just connect to that event as a signal directly. However if you wish to be notified when any signal is emitted, or for signals that do not follow the usual DBus convention, you can connect to this event.

The +name+ is the DBus signal name, and the +args+ is an array of arguments that were emitted with the signal.

client.proxies()

proxies = client.proxies([interface], [path_namespace], [options])

Create proxy javascript objects for a DBus interfaces. The proxies will have properties, methods and signals from the DBus +interface+, and allow for natural interaction. If no +interface+ is specified then the DBus bus name of the client is used. If no +path_namespace+ is provided then +"/"+ will be used.

Proxies will be automatically created for instances of the +interface+ available at the DBus service. The optional +path_namespace+ argument can be used to restrict the proxies for instances that have DBus paths which have the namespace path prefix.

proxy1 = proxies["/dbus/path1"];
proxy2 = proxies["/dbus/path2"];
for (proxy in proxies) {
    ...
}

The returned +proxies+ object will is used as a dictionary, and will have values containing proxies for DBus interface instances, with the keys being the DBus paths of those instances. It is possible to enumerate over the returned +proxies+.

Proxies will be automatically added and removed from the +proxies+ object as they appear and disappear in the service. The +proxies.onadded+ and +proxies.onremoved+ events will be emitted. DBus services may not support notifications of paths disappearing.

Use the +proxies.wait()+ function to be notified when the initial set of proxies has been populated.

Usually a proxies ask the +client+ to watch and be notified of changes to the relevant object or path. You can pass an +options+ argument with the +watch+ field set to +false+ to prevent this.

proxies.wait()

promise = proxies.wait()
proxies.wait(() => {
    ...
});

Wait for a +proxies+ object to populate its initial set of proxies. This function returns a promise. If a callback function is passed as an argument then that function will be invoked when the proxies are ready. If this method is called after the proxies have populated, then the promise will be resolved immediately, and any callback will be invoked immediately.

proxies.client

Set to the DBus client of the proxies. Will not change.

proxies.iface

Set to the DBus interface name of the proxies. Will not change.

proxies.path_namespace

Set to the DBus path namespace used which the proxies must have as a DBus path prefix. Will not change.

proxies.onadded

proxies.addEventListener("added", (event, proxy) => {
    ...
})

This event is emitted when a proxy is added to the +proxies+ object. The proxy will already have loaded.

proxies.onchanged

proxies.addEventListener("changed", (event, proxy) => {
    ...
})

This event is emitted when one of the proxy in the +proxies+ object changes its properties.

proxies.onremoved

proxies.addEventListener("removed", (event, proxy) => {
    ...
})

This event is emitted when a proxy is removed to the +proxies+ object.

client.call()

invocation = client.call(path, interface, method, args, [options])

Make a DBus method call.

The +path+ is the DBus object path to make the call on, +interface+ is the DBus interface for the method and +method+ is the name of the method to call. The +args+ is an array of arguments to pass to the method, each of which must be appropriate for the expected DBus type of that argument. The +args+ may be +null+ if no arguments are to be sent.

The returned value is a Promise that will complete successfully when the method returns, or fail if an error occurs.

If +options+ is specified it should be a plain javascript object, which may contain the following properties:

+flags+: A string containing DBus message flags. The character +"i"+ indicates to the dbus service that interactive authentication is allowed. If the entire +flags+ field is missing, then +"i"+ is set by default.
+type+: A valid DBus type signature to use when calling the method. In the absence of this, the DBus service will be introspected (and the result cached) to ask what the method type signature is.
+timeout+: The timeout of the call in milliseconds. The call will fail with the +"timeout"+ problem code. If "timeout" is not given, the call will never time out.

invocation.then()

invocation.then((args, options) => { ... })

This is a standard Promise method. It sets up a handler to be called when the DBus method call finishes successfully.

The +args+ argument is an array of return values from the DBus method. Each of them will be converted to an appropriate javascript type.

The +options+ argument may contain additional information about the reply. If the +type+ option was specified when performing the method call, then the +options+ in the reply here will also contain a +type+ field containing the DBus type signature of the output. If the +flags+ option was specified when performing the call then the +options+ in the reply here will contain message flags. Possible out message flags are:

+>+: A big endian message.
+<+: A little endian message.

invocation.catch()

invocation.catch(exception => { ... })

This is a standard Promise method. It sets up a handler to be called when the DBus method call fails.

The +exception+ object passed to the handler can have the following properties:

+problem+: A problem code string when a problem occurred starting or communicating with the DBus service. This is +null+ in the cases where an actual DBus error was occurred.
+name+: The DBus error name. This will be +null+ in cases where the failure was not due to a DBus error.
+message+: A DBus error message. This will be +null+ in cases where the failure was not due to a DBus error.

subscription = client.subscribe(match, (path, interface, signal, args) => { ... })

Subscribe to signals. The +match+ argument is a javascript plain object which defines what signals to subscribe to. Each property in the +match+ argument restricts signals subscribed to. If a property is not present then it is treated as a wildcard, matching anything. If an empty object is specified as +match+ then all signals will be subscribed to. The +match+ argument may contain the following properties:

+interface+: A DBus interface to match.
+path+: A DBus object path to match. May not be used together with the +path_namespace+ property. It should be a valid DBus object path, that is, it should have no trailing slash.
+path_namespace+: A DBus object path prefix to match. Any paths in the hierarchy below this top path will match. May not be used together with the +path+ property.
+member+: The DBus signal name to match.
+arg0+: Matches the first argument of a DBus message, which must be a string.

The handler passed as the second argument will be invoked when the signal is received. A +subscription+ is returned which can be used to remove the subscription by calling its +subscription.remove()+ method.

It is not a problem to subscribe to the same signals more than once, with identical or slightly different +match+ arguments.

subscription.remove()

subscription.remove()

Unsubscribe from the DBus signal subscription.

client.watch()

watch = client.watch(path)
watch = client.watch({ "path_namespace": path_namespace, "interface": interface })

Watch for property and interface changes on the given DBus object +path+ DBus +path_namespace+. If +interface+ is specified only properties on that DBus interface will be watched.

The +client.proxy()+ and +client.proxies()+ functions and the objects they return are high level wrappers around +client.watch()+.

The property and interface changes will be available in raw form on the +client.onnotify+ event.

Property and interface changes that are caused by a method call or signal will show up before that method call reply is received, or signal event is triggered. It should be possible to rely on this guarantee, unless the DBus service in question behaves incorrectly. Internally these watches work well with code that implements the ObjectManager portion of the DBus specification. If no ObjectManager implementation is available, the watch falls back to using DBus Introspection along with the usual PropertiesChanged signal. If the DBus service implements none of these, or implements them in an inconsistent manner, then this function will provide inconsistent or unexpected results.

The parameter is either a DBus +path+ or a plain javascript object with zero or more of the following fields. If an empty javascript object is used as an argument, then all paths, interfaces and properties will be watched.

+interface+: Watch properties on this DBus interface.
+path+: Watch interfaces and properties at this DBus path. May not be used together with the +path_namespace+ property.
+path_namespace+: Watch interfaces and properties under this DBus path. It should be a valid DBus object path, that is, it should have no trailing slash. If an ObjectManager implementation is available at this interface, then it is used. May not be used together with the +path+ property.

The returned value is a Promise that will complete successfully when the watch has populated its initial set of properties and interfaces, and these have been notified via +client.onnotify+.

A watch can be removed by calling the +watch.remove()+ method on the returned value. If identical watches are added more than once, then they must also be removed the same number of times before the removal takes effect.

watch.then()

watch.then(() => { ... })

This is a standard Promise method. It sets up a handler to be called when the watch has populated its initial properties and interfaces.

watch.catch()

watch.catch(ex => { ... })

This is a standard Promise method. It sets up a handler to be called if the watch fails to populate its initial properties and interfaces. Note that a watch will only fail if the DBus client closes or is somehow disconnected. It does not fail in the case of missing interfaces or properties.

watch.remove()

watch.remove()

Remove the watch. This may not have any immediate effect if other watches are in place. In particular, if identical watches are added more than once, then they must also be removed the same number of times before the removal takes effect.

client.onnotify

client.addEventListener("notify", data => { ... })

An event triggered when watched properties or interfaces change.

The +client.proxy()+ and +client.proxies()+ functions and the objects they return are high level wrappers around the +data+ provided by this event.

The +data+ has the following form:

{
    "/path1": {
        "org.Interface1": {
            "Prop1": "value",
            "Prop2": 5
        },
        "org.Interface2": null
    }
}

Multiple paths may be present, each of which may have multiple interfaces, each of which may have multiple properties. The first time a given path and interface is emitted from this signal, it will have all its properties and interfaces. Thereafter only changes are noted. If an interface is set to +null+, then that interface has disappeared.

client.notify()

client.notify(data)

Emits a synthetic +notify+ event. The +data+ argument should follow the same layout as described for the +notify+ event.

client.onmeta

client.onmeta = (ev, data) => { ... }

An event triggered when the meta data about watched interfaces is loaded.