D-Bus

7.7

top ← prev up next →

D-Bus

Jan Dvorak <mordae@anilinux.org>

Native D-Bus Client For Racket.

(require dbus)

package: dbus

1 Connecting

procedure
(dbus-connection? v) → boolean?
v : any/c

Determines if value is a D-Bus connection.

procedure
(dbus-connect-session-bus [auth-method]) → dbus-connection?
auth-method : (-> input-port? output-port? void?)
= dbus-auth-external

Connect to the session D-Bus by parsing the environment variable DBUS_SESSION_BUS_ADDRESS. Raises exn:fail:dbus if the environment variable is undefined, or if it contains an unsupported address format.

procedure
(dbus-connect-system-bus [auth-method]) → dbus-connection?
auth-method : (-> input-port? output-port? void?)
= dbus-auth-external

Connect to the system D-Bus by delegating to dbus-connect/socket with the default UNIX socket path.

procedure
(dbus-connect/address address [auth-method]) → dbus-connection?
address : string?
auth-method : (-> input-port? output-port? void?)
= dbus-auth-external

Connect to D-Bus using an address string such as might be contained in the DBUS_SESSION_BUS_ADDRESS environment variable. Raises exn:fail:dbus if the address format is unsupported.

procedure
(dbus-connect/socket [path auth-method]) → dbus-connection?
path : unix-socket-path? = "/var/run/dbus/system_bus_socket"
auth-method : (-> input-port? output-port? void?)
= dbus-auth-external

Connect to message bus via an UNIX domain socket using pluggable authentication mechanism.

procedure
(dbus-connect/tcp host port [auth-method]) → dbus-connection?
  host : string?
  port : (integer-in 1 65535)
   auth-method : (-> input-port? output-port? void?)
= dbus-auth-anonymous

Connect to message bus via a TCP socket using pluggable authentication mechanism. It does not make much of a sense to use anything else than dbus-auth-anonymous.

procedure
(dbus-auth-external in out) → void?
in : input-port?
out : output-port?

External authentication mechanism. Makes use of operating system capabilities to identify the user.

procedure
(dbus-auth-anonymous in out) → void?
in : input-port?
out : output-port?

Anonymous authentication mechanism. It’s usually not enabled on the server.

So, in order to connect to the system bus on a typical Linux system:

(current-dbus-connection
(dbus-connect/socket "/var/run/dbus/system_bus_socket"))

Or, to connect to a remote bus without authentication:

(current-dbus-connection
(dbus-connect/tcp "localhost" 1234))

procedure
(dbus-listen-evt [connection])
→
(evt/c (list/c dbus-object-path?
               dbus-interface-name?
               dbus-member-name?
               any/c))
  connection : dbus-connection? = (current-dbus-connection)

Event which reads a notification from the D-Bus connection.

2 Proxy Objects

In order to operate on remote objects, you first need to describe their interfaces and create proxy object instances that will map remote objects to regular ones.

class
dbus-object% : class?

superclass: object%

Generic D-Bus object proxy that have no methods defined.

constructor
(new dbus-object%
    [path path]
    [ [endpoint endpoint]
    [connection connection]])
→ (is-a?/c dbus-object%)
  path : dbus-object-path?
  endpoint : dbus-endpoint-name? = (current-dbus-endpoint)
  connection : dbus-connection? = (current-dbus-connection)
Every dbus-object% instance need to know these three things in order to communicate with the actual remote object. It can be advantageous to define current-dbus-connection or even current-dbus-endpoint beforehand.

value
dbus-object%/c : contract?

Contract for the dbus-object% class interface.

Objects without any methods are not very useful. In order to create proxies that can actually call anything, you need to make use of define-dbus-interface macro that will create a mixin with proxy calls to defined methods.

syntax
(define-dbus-interface interface-name
(method-name args-type) ...)

For example:

(define-dbus-interface dbus-interface<%> "org.freedesktop.DBus"
  (Hello "")
  (ListNames ""))

(define dbus% (dbus-interface<%> dbus-object%))
(define dbus (new dbus% (object-path "/org/freedesktop/DBus")
                        (endpoint "org.freedesktop.DBus")))
(send dbus ListNames)

2.1 Parameters

parameter
(current-dbus-connection) → (or/c #f dbus-connection?)
(current-dbus-connection connection) → void?
connection : (or/c #f dbus-connection?)

Parameter identifying current dbus connection used when constructing proxies. Comes handy when one uses just one connection, such as the system bus.

parameter
(current-dbus-endpoint) → (or/c #f dbus-endpoint-name?)
(current-dbus-endpoint endpoint) → void?
endpoint : (or/c #f dbus-endpoint-name?)

Parameter identifying current endpoint used when constructing proxies. Comes handy when one interfaces with just one peer, such as NetworkManager.

3 Other

3.1 Exceptions

procedure
(exn:fail:dbus? v) → boolean?
v : any/c

Generic bus failure exception.

procedure
(exn:fail:dbus:signature? v) → boolean?
v : any/c

Signature or encoding-related failure exception.

procedure
(exn:fail:dbus:connection? v) → boolean?
v : any/c

Communication-related failure exception.

procedure
(exn:fail:dbus:call? v) → boolean?
v : any/c

Remote call failed.

3.2 Bus Names

D-Bus uses a whole lot of specially formatted strings. You can use these predicates to check your data early.

procedure
(dbus-signature? v) → boolean?
v : any/c

Check that the value is a valid type signature, such as "ii" or "a(yv)".

procedure
(dbus-single-signature? v) → boolean?
v : any/c

Check that the value is a valid type signature that encodes a single type, such as "i" or "(ii)".

procedure
(dbus-object-path? v) → boolean?
v : any/c

Check that the value is a valid object path, such as "/org/freedesktop/DBus".

procedure
(dbus-interface-name? v) → boolean?
v : any/c

Check that the value is a valid interface name, such as "org.freedesktop.DBus".

procedure
(dbus-error-name? v) → boolean?
v : any/c

Check that the value is a valid error name, which has the same format as the interface name. An example could be "org.freedesktop.DBus.Error.Failed".

procedure
(dbus-member-name? v) → boolean?
v : any/c

Check that the value is a valid member name, such as "Hello".

procedure
(dbus-endpoint-name? v) → boolean?
v : any/c

Check that the value is a valid endpoint name, such as ":123.42" or "org.freedesktop.DBus".

4 Interfaces

(require dbus/interface)

package: dbus

mixin
dbus-introspectable<%> : (class? . -> . class?)

argument extends/implements:

dbus-object%/c

result implements:

dbus-introspectable<%>/c

Introspectable remote object.

method
(send a-dbus-introspectable Introspect) → string?
Retrieve the introspection XML document.

value
dbus-introspectable<%>/c : contract?

Contract for the dbus-introspectable<%> mixin interface.

mixin
dbus-properties<%> : (class? . -> . class?)

argument extends/implements:

dbus-object%/c

result implements:

dbus-properties<%>/c

Remote object with properties.

method
(send a-dbus-properties Get interface-name
property-name)
→ (cons/c dbus-single-signature? any/c)
  interface-name : dbus-interface-name?
  property-name : dbus-member-name?
Get property value.
method
(send a-dbus-properties Set interface-name
property-name
value) → void?
  interface-name : dbus-interface-name?
  property-name : dbus-member-name?
  value : (cons/c dbus-single-signature? any/c)
Set property to specified value.
method
(send a-dbus-properties GetAll interface-name) → dict?
  interface-name : dbus-interface-name?
Get values of all properties for given interface.

value
dbus-properties<%>/c : contract?

Contract for the dbus-properties<%> class interface.

mixin
dbus<%> : (class? . -> . class?)

argument extends/implements:

dbus-object%/c

result implements:

dbus<%>/c

Message bus interface.

method
(send a-dbus Hello) → string?
First method to call when communicating using a message bus. Returns your connection name.
method
(send a-dbus ListNames) → (listof string?)
Get list of names claimed on the bus.
method
(send a-dbus RequestName name flags)
→ exact-nonnegative-integer?
  name : string?
  flags : exact-nonnegative-integer?
Ask bus to assign you given name. See Message Bus Names section in the D-Bus specification for details.
method
(send a-dbus ReleaseName name) → exact-nonnegative-integer?
  name : string?
Release owned bus name.
method
(send a-dbus AddMatch rule) → void?
  rule : string?
Ask bus to route some messages your way. Used mainly for signal subscription. See Match Rules section in the D-Bus specification for details.
method
(send a-dbus RemoveMatch rule) → void?
  rule : string?
Cancel specified message matching rule.

value
dbus<%>/c : contract?

Contract for the dbus<%> class interface.

value
dbus% : (and/c dbus<%>/c dbus-introspectable<%>/c)

Proxy class for communication with the bus itself.

procedure
(dbus-manager [connection]) → object?
connection : dbus-connection? = (current-dbus-connection)

Returns instance of the dbus% class for specified connection.

top ← prev up next →