Struct zbus::Connection

pub struct Connection(_);

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 new_session, or to the system bus with new_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.

Since there are times when important messages arrive between a method call message is sent and its reply is received, Connection keeps an internal queue of incoming messages so that these messages are not lost and subsequent calls to receive_message will retreive messages from this queue first. The size of this queue is configurable through the set_max_queued method. The default size is 32. All messages that are received after the queue is full, are dropped.

Implementations

impl Connection

pub fn new_unix_client(stream: UnixStream, bus_connection: bool) -> Result<Self>

Create and open a D-Bus connection from a UnixStream.

The connection may either be set up for a bus connection, or not (for peer-to-peer communications).

Upon successful return, the connection is fully established and negotiated: D-Bus messages can be sent and received.

pub fn new_session() -> Result<Self>

Create a Connection to the session/user message bus.

pub fn new_system() -> Result<Self>

Create a Connection to the system-wide message bus.

pub fn new_for_address(address: &str, bus_connection: bool) -> Result<Self>

Create a Connection for the given D-Bus address.

pub fn new_unix_server(stream: UnixStream, guid: &Guid) -> Result<Self>

Create a server Connection for the given UnixStream and the server guid.

The connection will wait for incoming client authentication handshake & negotiation messages, for peer-to-peer communications.

Upon successful return, the connection is fully established and negotiated: D-Bus messages can be sent and received.

pub fn max_queued(&self) -> usize

Max number of messages to queue.

pub fn set_max_queued(self, max: usize) -> Self

Set the max number of messages to queue.

Since typically you'd want to set this at instantiation time, this method takes ownership of self and returns an owned Connection instance so you can use the builder pattern to set the value.

Example

let conn = zbus::Connection::new_session()?.set_max_queued(30);
assert_eq!(conn.max_queued(), 30);

// Do something usefull with `conn`..

pub fn server_guid(&self) -> &str

The server's GUID.

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

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

pub fn receive_message(&self) -> Result<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. If there are pending messages in the queue, the first one from the queue is returned instead of attempting to read the connection.

Warning

If you use this method in combination with Self::receive_specific or Proxy API on the same connection from multiple threads, you can end up with situation where this method takes away the message the other API is awaiting for and end up in a deadlock situation. It is therefore highly recommended not to use such a combination.

pub fn receive_specific<P>(&self, predicate: P) -> Result<Message> where
    P: Fn(&Message) -> Result<bool>, 

Receive a specific message.

This is the same as Self::receive_message, except that it takes a predicate function that decides if the message received should be returned by this method or not. Message received during this call that are not returned by it, are pushed to the queue to be picked by the susubsequent call to receive_message] or this method.

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.

Note: if this connection is in non-blocking mode, the message may not actually have been sent when this method returns, and you need to call the flush method so that pending messages are written to the socket.

pub fn call_method<B>(
    &self,
    destination: Option<&str>,
    path: &str,
    iface: Option<&str>,
    method_name: &str,
    body: &B
) -> Result<Message> where
    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 succesful reply, an Ok(Message) is returned. On error, an Err is returned. D-Bus error replies are returned as MethodError.

Note: This method will block until the response is received even if the connection is in non-blocking mode. If you don't want to block like this, use Connection::send_message.

pub fn emit_signal<B>(
    &self,
    destination: Option<&str>,
    path: &str,
    iface: &str,
    signal_name: &str,
    body: &B
) -> Result<()> where
    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<B>(
    &self,
    call: &Message,
    error_name: &str,
    body: &B
) -> Result<u32> where
    B: Serialize + Type, 

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.

Trait Implementations

impl AsRawFd for Connection

pub fn as_raw_fd(&self) -> RawFd

Extracts the raw file descriptor.

impl Clone for Connection

pub fn clone(&self) -> Connection

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Debug for Connection

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

Formats the value using the given formatter.