This is a reference-style documentation. It's not a tutorial for beginners, the reader should have knowledge of basic DBus concepts.
This section should be enough if you only want to consume DBus APIs.
The following code is assumed as a prolog to all following ones
{include:file:doc/ex-setup.rb}
{include:file:doc/ex-calling-methods.body.rb}
A method proxy always returns an array of values. This is to
accomodate the rare cases of a DBus method specifying more than one
out parameter. For nearly all methods you should use Method[0] or
Method.first
(I#30).
# wrong
if upower_i.SuspendAllowed # [false] is true!
upower_i.Suspend
end
# right
if upower_i.SuspendAllowed[0]
upower_i.Suspend
end
To access properties, think of the {DBus::ProxyObjectInterface interface} as a {DBus::ProxyObjectInterface#[] hash} keyed by strings, or use {DBus::ProxyObjectInterface#all_properties} to get an actual Hash of them.
{include:file:doc/ex-properties.body.rb}
(TODO a writable property example)
Note that unlike for methods where the interface is inferred if unambiguous, for properties the interface must be explicitly chosen. That is because {DBus::ProxyObject} uses the {DBus::ProxyObject Hash#[]} API to provide the {DBus::ProxyObjectInterface interfaces}, not the properties.
If a method call has a block attached, it is asynchronous and the block is invoked on receiving a method_return message or an error message
For asynchronous operation an event loop is necessary. Use {DBus::Main}:
# [set up signal handlers...]
main = DBus::Main.new
main << mybus
main.run
Alternately, run the GLib main loop and add your DBus connections to it via {DBus::Connection#glibize}.
To receive signals for a specific object and interface, use {DBus::ProxyObjectInterface#on_signal}(name, &block) or {DBus::ProxyObject#on_signal}(name, &block), for the default interface.
{include:file:doc/ex-signal.body.rb}
D-Bus booleans, numbers, strings, arrays and dictionaries become their straightforward Ruby counterparts.
Structs become arrays.
Object paths become strings.
Variants are simply unpacked to become their contained type. (ISSUE: prevents proper round-tripping!)
D-Bus has stricter typing than Ruby, so the library must decide which D-Bus type to choose. Most of the time the choice is dictated by the D-Bus signature.
If the signature expects a Variant (which is the case for all Properties!) then an explicit mechanism is needed.
A pair [{DBus::Type::Type}, value] specifies to marshall value as that specified type. The pair can be produced by {DBus.variant}(signature, value) which gives the same result as [{DBus.type}(signature), value].
ISSUE: using something else than cryptic signatures is even more painful than remembering the signatures!
foo_i['Bar'] = DBus.variant("au", [0, 1, 1, 2, 3, 5, 8])
Other values are tried to fit one of these: Boolean, Double, Array of Variants, Hash of String keyed Variants, String, Int32, Int64.
Deprecated: A pair [String, value], where String is a valid signature of a single complete type, marshalls value as that type. This will hit you when you rely on method (2) but happen to have a particular string value in an array.
If a byte array (ay) is expected you can pass a String too.
The bytes sent are according to the string's
encoding.
nil is not allowed by D-Bus and attempting to send it raises an exception
(but see I#16).
D-Bus calls can reply with an error instead of a return value. An error is translated to a Ruby exception, an instance of {DBus::Error}.
begin
network_manager.sleep
rescue DBus::Error => e
puts e unless e.name == "org.freedesktop.NetworkManager.AlreadyAsleepOrAwake"
end
Methods, properties and signals of a D-Bus object always belong to one of its interfaces.
Methods can be called without specifying their interface, as long as there is no ambiguity. There are two ways to resolve ambiguities:
assign an interface name to {DBus::ProxyObject#default_iface}.
get a specific {DBus::ProxyObjectInterface interface} of the object, with {DBus::ProxyObject#[]} and call methods from there.
Signals and properties only work with a specific interface.
Not there. An incomplete attempt was made.
When you want to provide a DBus API.
(check that client and service side have their counterparts)
This section lists the known deviations from version 0.19 of the specification.