Skip to main content

Connection

Struct Connection 

Source
pub struct Connection { /* private fields */ }
Expand description

A connection to a message bus. Cloning is cheap and every clone shares the socket and the reader thread; the socket closes when the last clone drops (or on close).

Exported handlers and signal callbacks that capture a clone keep the connection alive, so a long-lived owner calls unexport / remove_signal_handler or close when done. Handlers receive the connection in MethodCall and signal callbacks as an argument, so they rarely need to capture one.

Implementations§

Source§

impl Connection

Source

pub fn session() -> Result<Connection, Error>

Connects to the session bus named by DBUS_SESSION_BUS_ADDRESS, or to $XDG_RUNTIME_DIR/bus when the variable is unset.

§Errors

Returns Error::NoBus when neither variable names a usable address, and otherwise the errors of connect.

Source

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

Connects to a bus at a D-Bus server address such as unix:path=/run/user/1000/bus. Several ;-separated addresses are tried in order.

§Errors

Returns Error::Unsupported off unix, Error::NoBus or Error::Io when no address can be connected to, Error::Auth when the bus refuses authentication, and Error::Io or Error::Protocol when the opening exchange fails.

Source

pub fn unique_name(&self) -> &str

This connection’s unique bus name, such as :1.42.

Source

pub fn is_closed(&self) -> bool

Whether the connection has closed (the bus went away, or close).

Source

pub fn close(&self)

Closes the socket. Pending and later calls fail with Error::Disconnected, and the reader thread exits.

Source

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

Sends msg with a fresh serial, returning that serial.

§Errors

Returns Error::Disconnected when the connection is closed, Error::Protocol when msg cannot be encoded, and Error::Io when the write fails.

Source

pub fn call( &self, destination: &str, path: &str, interface: &str, member: &str, args: &[Value], ) -> Result<Vec<Value>, Error>

Calls a method and waits up to DEFAULT_TIMEOUT for its reply’s arguments.

§Errors

Returns the errors of call_with_timeout.

Source

pub fn call_with_timeout( &self, destination: &str, path: &str, interface: &str, member: &str, args: &[Value], timeout: Duration, ) -> Result<Vec<Value>, Error>

call with an explicit timeout.

§Errors

Returns Error::ReaderThread when called from the reader thread, Error::Remote when the peer answers with an error, Error::Timeout when no reply arrives in time, Error::Disconnected when the connection closes first, and Error::Protocol or Error::Io when the call cannot be encoded or written.

Source

pub fn call_no_reply( &self, destination: &str, path: &str, interface: &str, member: &str, args: &[Value], ) -> Result<(), Error>

Calls a method without waiting, asking the peer not to reply. Safe from handlers.

§Errors

Returns the errors of send.

Source

pub fn emit_signal( &self, path: &str, interface: &str, member: &str, args: &[Value], ) -> Result<(), Error>

Broadcasts a signal.

§Errors

Returns the errors of send.

Source

pub fn request_name(&self, name: &str, flags: u32) -> Result<u32, Error>

Asks the bus for a well-known name; returns a NAME_REPLY_* code.

§Errors

Returns the errors of call, and Error::Protocol when the bus’s reply carries no code.

Source

pub fn release_name(&self, name: &str) -> Result<(), Error>

Gives a well-known name back without waiting for the bus’s answer.

§Errors

Returns the errors of send.

Source

pub fn name_has_owner(&self, name: &str) -> bool

Whether some connection owns name; false when the bus cannot be asked.

Source

pub fn add_match(&self, rule: &str) -> Result<(), Error>

Asks the bus to route messages matching rule (such as type='signal',interface='org.example.Iface') to this connection.

§Errors

Returns the errors of call.

Source

pub fn remove_match(&self, rule: &str) -> Result<(), Error>

Withdraws a rule added with add_match, without waiting.

§Errors

Returns the errors of send.

Source

pub fn on_signal<F>(&self, filter: SignalFilter, callback: F) -> SubscriptionId
where F: Fn(&Connection, &Message) + Send + Sync + 'static,

Calls callback on the reader thread for every incoming signal that filter matches.

Source

pub fn remove_signal_handler(&self, id: SubscriptionId)

Removes a subscription made with on_signal.

Source

pub fn export<F>(&self, path: &str, handler: F) -> Result<(), Error>
where F: Fn(&MethodCall) -> Result<Vec<Value>, MethodError> + Send + Sync + 'static,

Answers method calls on object path with handler, which runs on the reader thread.

The connection answers org.freedesktop.DBus.Peer itself. For org.freedesktop.DBus.Introspectable.Introspect it asks the handler first and, when the handler answers UnknownMethod, replies with a minimal document listing the standard interfaces and any exported child objects (introspection_xml builds a handler’s own).

§Errors

Returns Error::Protocol when path is not a valid object path or is already exported.

Source

pub fn unexport(&self, path: &str)

Stops answering calls on path.

Trait Implementations§

Source§

impl Clone for Connection

Source§

fn clone(&self) -> Self

Returns a duplicate of the value. Read more
1.0.0 (const: unstable) · Source§

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

Performs copy-assignment from source. Read more
Source§

impl Debug for Connection

Source§

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

Formats the value using the given formatter. Read more

Auto Trait Implementations§

Blanket Implementations§

Source§

impl<T> Any for T
where T: 'static + ?Sized,

Source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
Source§

impl<T> Borrow<T> for T
where T: ?Sized,

Source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
Source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

Source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
Source§

impl<T> CloneToUninit for T
where T: Clone,

Source§

unsafe fn clone_to_uninit(&self, dest: *mut u8)

🔬This is a nightly-only experimental API. (clone_to_uninit)
Performs copy-assignment from self to dest. Read more
Source§

impl<T> From<T> for T

Source§

fn from(t: T) -> T

Returns the argument unchanged.

Source§

impl<T, U> Into<U> for T
where U: From<T>,

Source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

Source§

impl<T> ToOwned for T
where T: Clone,

Source§

type Owned = T

The resulting type after obtaining ownership.
Source§

fn to_owned(&self) -> T

Creates owned data from borrowed data, usually by cloning. Read more
Source§

fn clone_into(&self, target: &mut T)

Uses borrowed data to replace owned data, usually by cloning. Read more
Source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

Source§

type Error = !

The type returned in the event of a conversion error.
Source§

fn try_from(value: U) -> Result<T, !>

Performs the conversion.
Source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

Source§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
Source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.