logo

Crate zbus

source · []
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

Client

This code display a notification on your Freedesktop.org-compatible OS:

use std::{collections::HashMap, error::Error};

use zbus::{Connection, dbus_proxy};
use zvariant::Value;

#[dbus_proxy(
    interface = "org.freedesktop.Notifications",
    default_service = "org.freedesktop.Notifications",
    default_path = "/org/freedesktop/Notifications"
)]
trait Notifications {
    fn notify(
        &self,
        app_name: &str,
        replaces_id: u32,
        app_icon: &str,
        summary: &str,
        body: &str,
        actions: &[&str],
        hints: &HashMap<&str, &Value<'_>>,
        expire_timeout: i32,
    ) -> zbus::Result<u32>;
}

// 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 connection = Connection::session().await?;

    // `dbus_proxy` macro creates `NotificationProxy` based on `Notifications` trait.
    let proxy = NotificationsProxy::new(&connection).await?;
    let reply = proxy.notify(
        "my-app",
        0,
        "dialog-information",
        "A summary",
        "Some body",
        &[],
        &HashMap::new(),
        5000,
    ).await?;
    dbg!(reply);

    Ok(())
}

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 _ = 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."

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:

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 and disabling the default async-io feature:

[dependencies]
zbus = { version = "2", 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.

Re-exports

pub use zbus_names as names;
pub use zvariant;

Modules

The blocking API.

D-Bus standard interfaces.

Introspection XML support (xml feature)

Structs

A D-Bus 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 via InterfaceRef::get and InterfaceRef::get_mut.

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 single zbus::Connection.

A stream::Stream implementation that yields Message items.

An object server, holding server-side D-Bus objects & interfaces.

A stream::Stream implementation that yields UniqueName 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 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 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.

A tcp: address family.

Constants

Signature of the target’s native endian.

Traits

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 Definitions

Alias for a Result with the error type zbus::Error.

Attribute Macros

Attribute macro for implementing a D-Bus interface.

Attribute macro for defining D-Bus proxies (using zbus::Proxy and zbus::blocking::Proxy).

Derive Macros

Derive macro for implementing zbus::DBusError trait.