Expand description
§zbus
This is the main subcrate of the zbus project, that provides the API to interact with D-Bus. It takes care of the establishment of a connection, the creation, sending and receiving of different kind of D-Bus messages (method calls, signals etc) for you.
Status: Stable.
§Getting Started
The best way to get started with zbus is the book, where we start with basic D-Bus concepts and explain with code samples, how zbus makes D-Bus easy.
§Example code
We’ll create a simple D-Bus service and client to demonstrate the usage of zbus. Note that these
examples assume that a D-Bus broker is setup on your machine and you’ve a session bus running
(DBUS_SESSION_BUS_ADDRESS
environment variable must be set). This is guaranteed to be the case on
a typical Linux desktop session.
§Server
A simple service that politely greets whoever calls its SayHello
method:
use std::{error::Error, future::pending};
use zbus::{ConnectionBuilder, dbus_interface};
struct Greeter {
count: u64
}
#[dbus_interface(name = "org.zbus.MyGreeter1")]
impl Greeter {
// Can be `async` as well.
fn say_hello(&mut self, name: &str) -> String {
self.count += 1;
format!("Hello {}! I have been called {} times.", name, self.count)
}
}
// Although we use `async-std` here, you can use any async runtime of choice.
#[async_std::main]
async fn main() -> Result<(), Box<dyn Error>> {
let greeter = Greeter { count: 0 };
let _conn = ConnectionBuilder::session()?
.name("org.zbus.MyGreeter")?
.serve_at("/org/zbus/MyGreeter", greeter)?
.build()
.await?;
// Do other things or go to wait forever
pending::<()>().await;
Ok(())
}
You can use the following command to test it:
$ busctl --user call org.zbus.MyGreeter /org/zbus/MyGreeter org.zbus.MyGreeter1 SayHello s "Maria"
s "Hello Maria! I have been called 1 times."
§Client
Now let’s write the client-side code for MyGreeter
service:
use zbus::{Connection, Result, dbus_proxy};
#[dbus_proxy(
interface = "org.zbus.MyGreeter1",
default_service = "org.zbus.MyGreeter",
default_path = "/org/zbus/MyGreeter"
)]
trait MyGreeter {
async fn say_hello(&self, name: &str) -> Result<String>;
}
// Although we use `async-std` here, you can use any async runtime of choice.
#[async_std::main]
async fn main() -> Result<()> {
let connection = Connection::session().await?;
// `dbus_proxy` macro creates `MyGreaterProxy` based on `Notifications` trait.
let proxy = MyGreeterProxy::new(&connection).await?;
let reply = proxy.say_hello("Maria").await?;
println!("{reply}");
Ok(())
}
§Blocking API
While zbus is primarily asynchronous (since 2.0), blocking wrappers are provided for convenience.
§Compatibility with async runtimes
zbus is runtime-agnostic and should work out of the box with different Rust async runtimes. However, in order to achieve that, zbus spawns a thread per connection to handle various internal tasks. If that is something you would like to avoid, you need to:
- Use
ConnectionBuilder
and disable theinternal_executor
flag. - Ensure the internal executor keeps ticking continuously.
Moreover, by default zbus makes use of async-io
for all I/O, which also launches its own thread
to run its own internal executor.
§Special tokio support
Since tokio
is the most popular async runtime, zbus provides an easy way to enable tight
integration with it without you having to worry about any of the above: Enabling the tokio
feature:
# Sample Cargo.toml snippet.
[dependencies]
# Also disable the default `async-io` feature to avoid unused dependencies.
zbus = { version = "3", default-features = false, features = ["tokio"] }
That’s it! No threads launched behind your back by zbus (directly or indirectly) now and no need to tick any executors etc. 😼
Note: On Windows, the async-io
feature is currently required for UNIX domain socket support,
see the corresponding tokio issue on GitHub.
Note: On Windows, there is no standard implicit way to connect to a session bus. zbus provides
opt-in compatibility to the GDBus session bus discovery mechanism via the windows-gdbus
feature.
This mechanism uses a machine-wide mutex however, so only one GDBus session bus can run at a time.
Re-exports§
pub use zbus_names as names;
pub use zvariant;
Modules§
- The blocking API.
- D-Bus standard interfaces.
Structs§
- A D-Bus connection.
- A builder for
zbus::Connection
. - A D-Bus server GUID.
- Opaque structure that derefs to an
Interface
type. - Opaque structure that mutably derefs to an
Interface
type. - Wrapper over an interface, along with its corresponding
SignalContext
instance. A reference to the underlying interface may be obtained viaInterfaceRef::get
andInterfaceRef::get_mut
. - A bus match rule for subscribing to specific messages.
- Builder for
MatchRule
. - A D-Bus Message.
- A builder for
Message
- A collection of
MessageField
instances. - The message header, containing all the metadata about the message.
- The primary message header, which is present in all D-Bus messages.
- A position in the stream of
Message
objects received by a singlezbus::Connection
. - A
stream::Stream
implementation that yieldsMessage
items. - An object server, holding server-side D-Bus objects & interfaces.
- Owned sibling of
MatchRule
. - A
stream::Stream
implementation that yieldsUniqueName
when the bus owner changes. - A property changed event.
- A
stream::Stream
implementation that yields property change notifications. - A client-side interface proxy.
- Builder for proxies.
- A response wrapper that notifies after response has been sent.
- A signal emission context.
- A
stream::Stream
implementation that yields signal messages. - A
tcp:
D-Bus address.
Enums§
- A bus address
- Authentication mechanisms
- The properties caching mode.
- A helper type returned by
Interface
callbacks. - D-Bus code for endianness.
- The error type for
zbus
. - The path or path namespace.
- The dynamic message header.
- The message field code.
- Pre-defined flags that can be passed in Message header.
- Message header representing the D-Bus type of the message.
- Flags to use with
Proxy::call_with_flags
. - A
tcp:
address family.
Constants§
- Signature of the target’s native endian.
Traits§
- Async equivalent of
Drop
. - A trait that needs to be implemented by error types to be returned from D-Bus methods.
- The trait used to dispatch messages to an interface instance.
- Trait for the default associated values of a proxy.
- Helper trait for macro-generated code.
- Trait representing some transport layer over which the DBus protocol can be used
Type Aliases§
- Alias for a
Result
with the error typezbus::Error
.
Attribute Macros§
- Attribute macro for implementing a D-Bus interface.
- Attribute macro for defining D-Bus proxies (using
zbus::Proxy
andzbus::blocking::Proxy
).
Derive Macros§
- Derive macro for implementing
zbus::DBusError
trait.