Struct dbus::Connection

pub struct Connection { /* fields omitted */ }

A D-Bus connection. Start here if you want to get on the D-Bus!

Methods

impl Connection

fn get_private(bus: BusType) -> Result<Connection, Error>

Creates a new D-Bus connection.

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.

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

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

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

Sends a message over the D-Bus. The resulting handler can be added to a connectionitem handler.

fn unique_name(&self) -> String

Get the connection's unique name.

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.

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

Register an object path.

fn unregister_object_path(&self, path: &str)

Unregister an object path.

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

List registered object paths.

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

Register a name.

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

Release a name.

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.)

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

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

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.

fn watch_handle(&self, fd: RawFd, flags: c_uint) -> 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.

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

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

fn replace_message_callback(
    &self,
    f: Option<MessageCallback>
) -> Option<MessageCallback>

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::{Connection, BusType};
let c = Connection::get_private(BusType::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` and `ConnectionItem::WatchFd` would be ever yielded here.
}

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

use dbus::{Connection, BusType, MessageType};
let c = Connection::get_private(BusType::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.
}

Trait Implementations

impl Drop for Connection

fn drop(&mut self)

Executes the destructor for this type.

impl Debug for Connection

fn fmt(&self, f: &mut Formatter) -> Result<(), Error>

Formats the value using the given formatter.