Struct zbus::Connection

pub struct Connection { /* fields omitted */ }

A D-Bus connection.

A connection to a D-Bus bus, or a direct peer.

Once created, the connection is authenticated and negotiated and messages can be sent or received, such as method calls or signals.

For higher-level message handling (typed functions, introspection, documentation reasons etc), it is recommended to wrap the low-level D-Bus messages into Rust functions with the dbus_proxy and dbus_interface macros instead of doing it directly on a Connection.

Typically, a connection is made to the session bus with session, or to the system bus with system. Then the connection is shared with the Proxy and ObjectServer instances.

Connection implements Clone and cloning it is a very cheap operation, as the underlying data is not cloned. This makes it very convenient to share the connection between different parts of your code. Connection also implements std::marker::Sync andstd::marker::Send so you can send and share a connection instance across threads as well.

Connection keeps an internal ringbuffer of incoming message. The maximum capacity of this ringbuffer is configurable through the set_max_queued method. The default size is 64. When the buffer is full, messages are dropped to create room, starting from the oldest one.

Implementations

impl Connection

pub fn session() -> Result<Self>

Create a Connection to the session/user message bus.

pub fn system() -> Result<Self>

Create a Connection to the system-wide message bus.

pub fn max_queued(&self) -> usize

Max number of messages to queue.

pub fn set_max_queued(self, max: usize)

Set the max number of messages to queue.

pub fn server_guid(&self) -> &str

The server’s GUID.

pub fn unique_name(&self) -> Option<&OwnedUniqueName>

The unique name as assigned by the message bus or None if not a message bus connection.

pub fn receive_message(&self) -> Result<Arc<Message>>

Fetch the next message from the connection.

Read from the connection until a message is received or an error is reached. Return the message on success.

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

Send msg to the peer.

The connection sets a unique serial number on the message before sending it off.

On successfully sending off msg, the assigned serial number is returned.

pub fn call_method<'d, 'p, 'i, 'm, D, P, I, M, B>(
    &self,
    destination: Option<D>,
    path: P,
    iface: Option<I>,
    method_name: M,
    body: &B
) -> Result<Arc<Message>> where
    D: TryInto<BusName<'d>>,
    P: TryInto<ObjectPath<'p>>,
    I: TryInto<InterfaceName<'i>>,
    M: TryInto<MemberName<'m>>,
    D::Error: Into<Error>,
    P::Error: Into<Error>,
    I::Error: Into<Error>,
    M::Error: Into<Error>,
    B: Serialize + Type, 

Send a method call.

Create a method-call message, send it over the connection, then wait for the reply. Incoming messages are received through receive_message until the matching method reply (error or return) is received.

On successful reply, an Ok(Message) is returned. On error, an Err is returned. D-Bus error replies are returned as MethodError.

pub fn emit_signal<'d, 'p, 'i, 'm, D, P, I, M, B>(
    &self,
    destination: Option<D>,
    path: P,
    iface: I,
    signal_name: M,
    body: &B
) -> Result<()> where
    D: TryInto<BusName<'d>>,
    P: TryInto<ObjectPath<'p>>,
    I: TryInto<InterfaceName<'i>>,
    M: TryInto<MemberName<'m>>,
    D::Error: Into<Error>,
    P::Error: Into<Error>,
    I::Error: Into<Error>,
    M::Error: Into<Error>,
    B: Serialize + Type, 

Emit a signal.

Create a signal message, and send it over the connection.

pub fn reply<B>(&self, call: &Message, body: &B) -> Result<u32> where
    B: Serialize + Type, 

Reply to a message.

Given an existing message (likely a method call), send a reply back to the caller with the given body.

Returns the message serial number.

pub fn reply_error<'e, E, B>(
    &self,
    call: &Message,
    error_name: E,
    body: &B
) -> Result<u32> where
    B: Serialize + Type,
    E: TryInto<ErrorName<'e>>,
    E::Error: Into<Error>, 

Reply an error to a message.

Given an existing message (likely a method call), send an error reply back to the caller with the given error_name and body.

Returns the message serial number.

pub fn is_bus(&self) -> bool

Checks if self is a connection to a message bus.

This will return false for p2p connections.

pub fn inner(&self) -> &Connection

Get a reference to the underlying async Connection.

pub fn into_inner(self) -> Connection

Get the underlying async Connection, consuming self.

Trait Implementations

impl AsRawFd for Connection

fn as_raw_fd(&self) -> RawFd

Extracts the raw file descriptor.

impl Clone for Connection

fn clone(&self) -> Connection

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Connection

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

Formats the value using the given formatter.

impl From<Connection> for Connection

fn from(conn: Connection) -> Self

Performs the conversion.

impl From<Connection> for Connection

fn from(conn: Connection) -> Self

Performs the conversion.