[][src]Crate zbus

This crate provides the main API you will use to interact with D-Bus from Rust. 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.

zbus crate is currently Linux-specific1.

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;
use std::error::Error;

use zbus::dbus_proxy;
use zvariant::Value;

#[dbus_proxy]
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>;
}

fn main() -> Result<(), Box<dyn Error>> {
    let connection = zbus::Connection::new_session()?;

    let proxy = NotificationsProxy::new(&connection)?;
    let reply = proxy.notify(
        "my-app",
        0,
        "dialog-information",
        "A summary",
        "Some body",
        &[],
        HashMap::new(),
        5000,
    )?;
    dbg!(reply);

    Ok(())
}

Server

A simple service that politely greets whoever calls its SayHello method:

use std::error::Error;
use std::convert::TryInto;
use zbus::{dbus_interface, fdo};

struct Greeter {
    count: u64
};

#[dbus_interface(name = "org.zbus.MyGreeter1")]
impl Greeter {
    fn say_hello(&mut self, name: &str) -> String {
        self.count += 1;
        format!("Hello {}! I have been called: {}", name, self.count)
    }
}

fn main() -> Result<(), Box<dyn Error>> {
    let connection = zbus::Connection::new_session()?;
    fdo::DBusProxy::new(&connection)?.request_name(
        "org.zbus.MyGreeter",
        fdo::RequestNameFlags::ReplaceExisting.into(),
    )?;

    let mut object_server = zbus::ObjectServer::new(&connection);
    let mut greeter = Greeter { count: 0 };
    object_server.at(&"/org/zbus/MyGreeter".try_into()?, greeter)?;
    loop {
        if let Err(err) = object_server.try_handle_next() {
            eprintln!("{}", err);
        }
    }
}

You can use the following command to test it:

$ busctl --user call \
    org.zbus.MyGreeter \
    /org/zbus/MyGreeter \
    org.zbus.MyGreeter1 \
    SayHello s "Maria"
Hello Maria!
$

Asynchronous API

Currently, only low-level asynchronous API is provided. You can do everything you can through it that you can do through the high-level asynchronous API (when it exists), it's not at all as hard to use as it may sound.


  1. Support for other OS exist, but it is not supported to the same extent. D-Bus clients in javascript (running from any browser) do exist though. And zbus may also be working from the browser sometime in the future too, thanks to Rust 🦀 and WebAssembly 🕸. 

Modules

azync

The asynchronous API.

fdo

D-Bus standard interfaces.

handshake
raw
xml

Introspection XML support (xml feature)

Structs

Connection

A D-Bus connection.

Guid

A D-Bus server GUID.

Message

A D-Bus Message.

MessageFields

A collection of MessageField instances.

MessageHeader

The message header, containing all the metadata about the message.

MessagePrimaryHeader

The primary message header, which is present in all D-Bus messages.

ObjectServer

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

OwnedFd

An owned representation of a file descriptor

Proxy

A client-side interface proxy.

SignalReceiver

Receives signals for Proxy instances.

Enums

EndianSig

D-Bus code for endianness.

Error

The error type for zbus.

MessageError

Error type returned by Message methods.

MessageField

The dynamic message header.

MessageFieldCode

The message field code.

MessageFlags

Pre-defined flags that can be passed in Message header.

MessageType

Message header representing the D-Bus type of the message.

Constants

NATIVE_ENDIAN_SIG

Signature of the target's native endian.

Traits

Interface

The trait used to dispatch messages to an interface instance.

Type Definitions

Result

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

Attribute Macros

dbus_interface

Attribute macro for implementing a D-Bus interface.

dbus_proxy

Attribute macro for defining a D-Bus proxy (using zbus Proxy).

Derive Macros

DBusError

Derive macro for defining a D-Bus error.