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 new_session, or to the system bus with new_system. Then the connection is shared with the Proxy and ObjectServer instances.

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 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 a default message handler has been registered on this connection through set_default_message_handler, it will first get to decide the fate of the received message.

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<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 (and by the default message handler) 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.

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 set_default_message_handler(
    &mut self,
    handler: Box<dyn FnMut(Message) -> Option<Message>>
)

Set a default handler for incoming messages on this connection.

This is the handler that will be called on all messages received during receive_message call. If the handler callback returns a message (which could be a different message than it was given), receive_message will return it to its caller.

pub fn reset_default_message_handler(&mut self)

Reset the default message handler.

Remove the previously set message handler from set_default_message_handler.

Trait Implementations

impl AsRawFd for Connection

fn as_raw_fd(&self) -> RawFd

Extracts the raw file descriptor.

impl Debug for Connection

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

Formats the value using the given formatter.