Crate zbus[−][src]
Expand description
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.
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
The asynchronous API.
D-Bus standard interfaces.
Introspection XML support (xml
feature)
Structs
A D-Bus connection.
A D-Bus server GUID.
A D-Bus 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.
An object server, holding server-side D-Bus objects & interfaces.
An owned representation of a file descriptor
A client-side interface proxy.
Receives signals for Proxy
instances.
Enums
D-Bus code for endianness.
The error type for zbus
.
Error type returned by Message
methods.
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.
Constants
Signature of the target’s native endian.
Traits
The trait used to dispatch messages to an interface instance.
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 a D-Bus proxy (using zbus Proxy
).
Derive Macros
Derive macro for defining a D-Bus error.