Struct zbus::ObjectServer

pub struct ObjectServer<'a> { /* fields omitted */ }

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

Object servers hold interfaces on various object paths, and expose them over D-Bus.

All object paths will have the standard interfaces implemented on your behalf, such as org.freedesktop.DBus.Introspectable or org.freedesktop.DBus.Properties.

NOTE: The lifetime 'a on the ObjectServer struct is bogus and only exists for backwards-compatibility and will be dropped in the next major release (i-e 2.0). This means that 'a can be considered 'static for all intents and purposes.

Example

This example exposes the org.myiface.Example.Quit method on the /org/zbus/path path.

use zbus::{Connection, ObjectServer, dbus_interface};
use std::rc::Rc;
use std::cell::RefCell;

struct Example {
    // Interfaces are owned by the ObjectServer. They can have
    // `&mut self` methods.
    //
    // If you need a shared state, you can use a RefCell for ex:
    quit: Rc<RefCell<bool>>,
}

impl Example {
    fn new(quit: Rc<RefCell<bool>>) -> Self {
        Self { quit }
    }
}

#[dbus_interface(name = "org.myiface.Example")]
impl Example {
    // This will be the "Quit" D-Bus method.
    fn quit(&self) {
        *self.quit.borrow_mut() = true;
    }

    // See `dbus_interface` documentation to learn
    // how to expose properties & signals as well.
}

let connection = Connection::new_session()?;
let mut object_server = ObjectServer::new(&connection);
let quit = Rc::new(RefCell::new(false));

let interface = Example::new(quit.clone());
object_server.at(&"/org/zbus/path".try_into()?, interface)?;

loop {
    if let Err(err) = object_server.try_handle_next() {
        eprintln!("{}", err);
    }

    if *quit.borrow() {
        break;
    }
}

Implementations

impl<'a> ObjectServer<'a>

pub fn new(connection: &Connection) -> Self

Creates a new D-Bus ObjectServer for a given connection.

pub fn at<I>(&mut self, path: &ObjectPath<'_>, iface: I) -> Result<bool> where
    I: Interface, 

Register a D-Bus Interface at a given path. (see the example above)

If the interface already exists at this path, returns false.

pub fn remove<I>(&mut self, path: &ObjectPath<'_>) -> Result<bool> where
    I: Interface, 

Unregister a D-Bus Interface at a given path.

If there are no more interfaces left at that path, destroys the object as well. Returns whether the object was destroyed.

pub fn with<F, I>(&self, path: &ObjectPath<'_>, func: F) -> Result<()> where
    F: Fn(&I) -> Result<()>,
    I: Interface, 

Run func with the given path & interface.

Run the function func with the interface at path. If the interface was not found, return Error::InterfaceNotFound.

This function is useful to emit signals outside of a dispatched handler:

object_server.with(path, |iface: &MyIface| {
  iface.emit_signal()
})?;

pub fn local_node_emit_signal<B>(
    destination: Option<&str>,
    iface: &str,
    signal_name: &str,
    body: &B
) -> Result<()> where
    B: Serialize + Type, 

Emit a signal on the currently dispatched node.

This is an internal helper function to emit a signal on on the current node. You shouldn't call this method directly, rather with the derived signal implementation from dbus_interface.

Panics

This method will panic if called from outside of a node context. Use ObjectServer::with to bring a node into the current context.

pub fn dispatch_message(&mut self, msg: &Message) -> Result<bool>

Dispatch an incoming message to a registered interface.

The object server will handle the message by:

• looking up the called object path & interface,

• calling the associated method if one exists,

• returning a message (responding to the caller with either a return or error message) to the caller through the associated server connection.

Returns an error if the message is malformed, true if it's handled, false otherwise.

Note

This API is subject to change, or becoming internal-only once zbus provides a general mechanism to dispatch messages.

pub fn try_handle_next(&mut self) -> Result<Option<Message>>

Receive and handle the next message from the associated connection.

This function will read the incoming message from receive_message() of the associated connection and pass it to dispatch_message(). If the message was handled by an an interface, it returns Ok(None). If not, it returns the received message.

Returns an error if the message is malformed or an error occured.

Note

This API is subject to change, or becoming internal-only once zbus provides a general mechanism to dispatch messages.

Trait Implementations

impl<'a> Debug for ObjectServer<'a>

pub fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.