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
7.1

D-Bus

Jan Dvorak <[email protected]>

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.