D-Bus
1 Connecting
dbus-connection?
dbus-connect-session-bus
dbus-connect-system-bus
dbus-connect/  address
dbus-connect/  socket
dbus-connect/  tcp
dbus-auth-external
dbus-auth-anonymous
dbus-listen-evt
2 Proxy Objects
dbus-object%
new
dbus-object%/  c
define-dbus-interface
2.1 Parameters
current-dbus-connection
current-dbus-endpoint
3 Other
3.1 Exceptions
exn:  fail:  dbus?
exn:  fail:  dbus:  signature?
exn:  fail:  dbus:  connection?
exn:  fail:  dbus:  call?
3.2 Bus Names
dbus-signature?
dbus-single-signature?
dbus-object-path?
dbus-interface-name?
dbus-error-name?
dbus-member-name?
dbus-endpoint-name?
4 Interfaces
dbus-introspectable<%>
Introspect
dbus-introspectable<%>/  c
dbus-properties<%>
Get
Set
Get  All
dbus-properties<%>/  c
dbus<%>
Hello
List  Names
Request  Name
Release  Name
Add  Match
Remove  Match
dbus<%>/  c
dbus%
dbus-manager
8.12

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.

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.

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.

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.

Contract for the dbus<%> class interface.

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.