Struct fwupd_dbus::Client

pub struct Client { /* fields omitted */ }

A DBus client for interacting with the fwupd daemon.

Methods

impl Client

pub fn new() -> Result<Self, Error>

pub fn activate<D: AsRef<DeviceId>>(&self, id: D) -> Result<(), Error>

Activate a firmware update on the device.

pub fn clear_results<D: AsRef<DeviceId>>(&self, id: D) -> Result<(), Error>

Clears the results of an offline update.

pub fn daemon_version(&self) -> Result<Box<str>, Error>

The version of this daemon.

pub fn details<H: IntoRawFd>(
    &self,
    handle: H
) -> Result<Vec<HashMap<String, DynVariant>>, Error>

Gets details about a local firmware file.

pub fn devices(&self) -> Result<Vec<Device>, Error>

Gets a list of all the devices that are supported.

pub fn downgrades<D: AsRef<DeviceId>>(
    &self,
    device_id: D
) -> Result<Vec<Release>, Error>

Get a list of all the downgrades possible for a specific device.

pub fn fetch_firmware_from_release<C: FnMut(FlashEvent)>(
    &self,
    client: &HttpClient,
    device: &Device,
    release: &Release,
    callback: Option<C>
) -> Result<(PathBuf, Option<File>), Error>

Fetches firmware from a remote and caches it for later use.

Firmware will only be fetched if it has not already been cached, or the cached firmware has an invalid checksum.

pub fn update_device_with_release<F: FnMut(FlashEvent)>(
    &self,
    client: &HttpClient,
    device: &Device,
    release: &Release,
    flags: InstallFlags,
    callback: Option<F>
) -> Result<(), Error>

Update firmware for a Device with the firmware specified in a Release.

pub fn history<H: IntoRawFd>(&self, handle: H) -> Result<Vec<Device>, Error>

Gets a list of all the past firmware updates.

pub fn install<D: AsRef<DeviceId>, H: IntoRawFd>(
    &self,
    id: D,
    reason: &str,
    filename: &Path,
    handle: Option<H>,
    flags: InstallFlags
) -> Result<(), Error>

Schedules a firmware to be installed.

pub fn listen_signals<'a>(
    &'a self,
    cancellable: Arc<AtomicBool>
) -> impl Iterator<Item = Signal> + 'a

Listens for signals from the DBus daemon.

pub fn modify_device<D: AsRef<DeviceId>>(
    &self,
    device_id: D,
    key: &str,
    value: &str
) -> Result<(), Error>

Modifies a device in some way.

pub fn modify_remote<R: AsRef<RemoteId>>(
    &self,
    remote_id: R,
    key: &str,
    value: &str
) -> Result<(), Error>

Modifies a remote in some way.

pub fn percentage(&self) -> Result<u8, Error>

The job percentage completion, or 0 for unknown.

pub fn ping(&self) -> Result<(), Error>

pub fn releases<D: AsRef<DeviceId>>(
    &self,
    device_id: D
) -> Result<Vec<Release>, Error>

Gets a list of all the releases for a specific device.

pub fn remote<D: AsRef<RemoteId>>(&self, id: D) -> Result<Remote, Error>

Find the remote with the given ID.

pub fn remotes(&self) -> Result<Vec<Remote>, Error>

Gets the list of remotes.

pub fn results<D: AsRef<DeviceId>>(
    &self,
    id: D
) -> Result<Option<Device>, Error>

Gets the results of an offline update.

pub fn status(&self) -> Result<Status, Error>

The daemon status, e.g. Decompressing.

pub fn tainted(&self) -> Result<bool, Error>

If the daemon has been tainted with a third party plugin.

pub fn unlock<D: AsRef<DeviceId>>(&self, id: D) -> Result<(), Error>

Unlock the device to allow firmware access.

pub fn update_metadata<D: IntoRawFd, S: IntoRawFd, R: AsRef<RemoteId>>(
    &self,
    remote_id: R,
    data: D,
    signature: S
) -> Result<(), Error>

Adds AppStream resource information from a session client.

pub fn upgrades<D: AsRef<DeviceId>>(
    &self,
    device_id: D
) -> Result<Vec<Release>, Error>

Get a list of all the upgrades possible for a specific device.

pub fn verify<D: AsRef<DeviceId>>(&self, id: D) -> Result<(), Error>

Verifies firmware on a device by reading it back and performing a cryptographic hash, typically SHA1.

pub fn verify_update<D: AsRef<DeviceId>>(&self, id: D) -> Result<(), Error>

Updates the cryptographic hash stored for a device.

Methods from Deref<Target = Connection>

pub fn register(&self) -> Result<(), Error>

Registers a new D-Bus connection with the bus.

Note: get_private does this automatically, useful with open_private

pub fn is_connected(&self) -> bool

Gets whether the connection is currently open.

pub fn send_with_reply_and_block(
    &self,
    msg: Message,
    timeout_ms: i32
) -> Result<Message, Error>

Sends a message over the D-Bus and waits for a reply. This is usually used for method calls.

pub fn send(&self, msg: Message) -> Result<u32, ()>

Sends a message over the D-Bus without waiting. Useful for sending signals and method call replies.

pub fn send_with_reply<'a, F>(
    &self,
    msg: Message,
    f: F
) -> Result<MessageReply<F>, ()> where
    F: 'a + FnOnce(Result<&Message, Error>), 

Sends a message over the D-Bus, returning a MessageReply.

Call add_handler on the result to start waiting for reply. This should be done before next call to incoming or iter.

pub fn add_handler<H>(&self, h: H) where
    H: 'static + MsgHandler, 

Adds a message handler to the connection.

Example

use std::{cell, rc};
use dbus::{ffidisp::Connection, Message};

let c = Connection::new_session().unwrap();
let m = Message::new_method_call("org.freedesktop.DBus", "/", "org.freedesktop.DBus", "ListNames").unwrap();

let done: rc::Rc<cell::Cell<bool>> = Default::default();
let done2 = done.clone();
c.add_handler(c.send_with_reply(m, move |reply| {
    let v: Vec<&str> = reply.unwrap().read1().unwrap(); 
    println!("The names on the D-Bus are: {:?}", v);
    done2.set(true);
}).unwrap());
while !done.get() { c.incoming(100).next(); }

pub fn extract_handler(&self) -> Option<Box<dyn MsgHandler + 'static>>

Removes a MsgHandler from the connection.

If there are many MsgHandlers, it is not specified which one will be returned.

There might be more methods added later on, which give better ways to deal with the list of MsgHandler currently on the connection. If this would help you, please file an issue.

pub fn unique_name(&self) -> String

Get the connection's unique name.

pub fn iter(&self, timeout_ms: i32) -> ConnectionItems

Check if there are new incoming events

If there are no incoming events, ConnectionItems::Nothing will be returned. See ConnectionItems::new if you want to customize this behaviour.

pub fn incoming(&self, timeout_ms: u32) -> ConnMsgs<&Connection>

Check if there are new incoming events

Supersedes "iter".

pub fn register_object_path(&self, path: &str) -> Result<(), Error>

Register an object path.

pub fn unregister_object_path(&self, path: &str)

Unregister an object path.

pub fn list_registered_object_paths(&self, path: &str) -> Vec<String>

List registered object paths.

pub fn register_name(
    &self,
    name: &str,
    flags: u32
) -> Result<DBusRequestNameReply, Error>

Register a name.

pub fn release_name(&self, name: &str) -> Result<DBusReleaseNameReply, Error>

Release a name.

pub fn add_match(&self, rule: &str) -> Result<(), Error>

Add a match rule to match messages on the message bus.

See the unity_focused_window example for how to use this to catch signals. (The syntax of the "rule" string is specified in the D-Bus specification.)

pub fn remove_match(&self, rule: &str) -> Result<(), Error>

Remove a match rule to match messages on the message bus.

pub fn watch_fds(&self) -> Vec<Watch>

Async I/O: Get an up-to-date list of file descriptors to watch.

See the Watch struct for an example.

pub fn watch_handle(&self, fd: i32, flags: u32) -> ConnectionItems

Async I/O: Call this function whenever you detected an event on the Fd, Flags are a set of WatchEvent bits. The returned iterator will return pending items only, never block for new events.

See the Watch struct for an example.

pub fn with_path<'a, D, P>(
    &'a self,
    dest: D,
    path: P,
    timeout_ms: i32
) -> ConnPath<'a, &'a Connection> where
    D: Into<BusName<'a>>,
    P: Into<Path<'a>>, 

Create a convenience struct for easier calling of many methods on the same destination and path.

pub fn replace_message_callback(
    &self,
    f: Option<Box<dyn FnMut(&Connection, Message) + 'static>>
) -> Option<Box<dyn FnMut(&Connection, Message) + 'static>>

Replace the default message callback. Returns the previously set callback.

By default, when you call ConnectionItems::next, all relevant incoming messages are returned through the ConnectionItems iterator, and irrelevant messages are passed on to libdbus's default handler. If you need to customize this behaviour (i e, to handle all incoming messages yourself), you can set this message callback yourself. A few caveats apply:

Return true from the callback to disable libdbus's internal handling of the message, or false to allow it. In other words, true and false correspond to DBUS_HANDLER_RESULT_HANDLED and DBUS_HANDLER_RESULT_NOT_YET_HANDLED respectively.

Be sure to call the previously set callback from inside your callback, if you want, e.g. ConnectionItems::next to yield the message.

You can unset the message callback (might be useful to satisfy the borrow checker), but you will get a panic if you call ConnectionItems::next while the message callback is unset. The message callback will be temporary unset while inside a message callback, so calling ConnectionItems::next recursively will also result in a panic.

If your message callback panics, ConnectionItems::next will panic, too.

Examples

Replace the default callback with our own:

use dbus::ffidisp::Connection;
let c = Connection::new_session().unwrap();
// Set our callback
c.replace_message_callback(Some(Box::new(move |conn, msg| {
    println!("Got message: {:?}", msg.get_items());
    // Let libdbus handle some things by default,
    // like "nonexistent object" error replies to method calls
    false
})));

for _ in c.iter(1000) {
   // Only `ConnectionItem::Nothing` would be ever yielded here.
}

Chain our callback to filter out some messages before iter().next():

use dbus::{ffidisp::Connection, MessageType};
let c = Connection::new_session().unwrap();
// Take the previously set callback
let mut old_cb = c.replace_message_callback(None).unwrap();
// Set our callback
c.replace_message_callback(Some(Box::new(move |conn, msg| {
    // Handle all signals on the spot
    if msg.msg_type() == MessageType::Signal {
        println!("Got signal: {:?}", msg.get_items());
        // Stop all further processing of the message
        return true;
    }
    // Delegate the rest of the messages to the previous callback
    // in chain, e.g. to have them yielded by `iter().next()`
    old_cb(conn, msg)
})));

for _ in c.iter(1000) {
   // `ConnectionItem::Signal` would never be yielded here.
}

pub fn set_watch_callback(&self, f: Box<dyn Fn(Watch) + 'static + Send>)

Sets a callback to be called if a file descriptor status changes.

For async I/O. In rare cases, the number of fds to poll for read/write can change. If this ever happens, you'll get a callback. The watch changed is provided as a parameter.

In rare cases this might not even happen in the thread calling anything on the connection, so the callback needs to be Send. A mutex is held during the callback. If you try to call set_watch_callback from a callback, you will deadlock.

(Previously, this was instead put in a ConnectionItem queue, but this was not working correctly. see https://github.com/diwic/dbus-rs/issues/99 for additional info.)

Trait Implementations

impl AsRef<Connection> for Client

fn as_ref(&self) -> &Connection

Performs the conversion.

impl Borrow<Connection> for Client

fn borrow(&self) -> &Connection

Immutably borrows from an owned value.

impl Deref for Client

type Target = Connection

The resulting type after dereferencing.

fn deref(&self) -> &Self::Target

Dereferences the value.