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

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

Creates a new D-Bus connection.

pub fn open_private(address: &str) -> Result<Connection, Error>

Creates a new D-Bus connection to a remote address.

Note: for all common cases (System / Session bus) you probably want "get_private" instead.

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: FnOnce(Result<&Message, Error>) + 'a>(     &self,     msg: Message,     f: F ) -> Result<MessageReply<F>, ()>

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: MsgHandler + 'static>(&self, h: H)

Adds a message handler to the connection.

Example

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

let c = Connection::get_private(BusType::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<MsgHandler>>

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.

Important traits for ConnectionItems<'a>

impl<'a> Iterator for ConnectionItems<'a> type Item = ConnectionItem;

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.

Important traits for ConnMsgs<C>

impl<C: Deref<Target = Connection>> Iterator for ConnMsgs<C> type Item = Message;

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

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.

Important traits for Vec<u8>

impl Write for Vec<u8>

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<RequestNameReply, Error>

Register a name.

pub fn release_name(&self, name: &str) -> Result<ReleaseNameReply, 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.

Important traits for Vec<u8>

impl Write for Vec<u8>

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.

Important traits for ConnectionItems<'a>

impl<'a> Iterator for ConnectionItems<'a> type Item = ConnectionItem;

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

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

pub 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` 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.
}

pub fn set_watch_callback(&self, f: Box<Fn(Watch) + 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 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.