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
impl Connection
Sourcepub fn session() -> Result<Connection, Error>
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.
Sourcepub fn connect(address: &str) -> Result<Connection, Error>
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.
Sourcepub fn unique_name(&self) -> &str
pub fn unique_name(&self) -> &str
This connection’s unique bus name, such as :1.42.
Sourcepub fn is_closed(&self) -> bool
pub fn is_closed(&self) -> bool
Whether the connection has closed (the bus went away, or close).
Sourcepub fn close(&self)
pub fn close(&self)
Closes the socket. Pending and later calls fail with Error::Disconnected, and the
reader thread exits.
Sourcepub fn send(&self, msg: Message) -> Result<u32, Error>
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.
Sourcepub fn call(
&self,
destination: &str,
path: &str,
interface: &str,
member: &str,
args: &[Value],
) -> Result<Vec<Value>, Error>
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.
Sourcepub fn call_with_timeout(
&self,
destination: &str,
path: &str,
interface: &str,
member: &str,
args: &[Value],
timeout: Duration,
) -> Result<Vec<Value>, Error>
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.
Sourcepub fn call_no_reply(
&self,
destination: &str,
path: &str,
interface: &str,
member: &str,
args: &[Value],
) -> Result<(), Error>
pub fn call_no_reply( &self, destination: &str, path: &str, interface: &str, member: &str, args: &[Value], ) -> Result<(), Error>
Sourcepub fn emit_signal(
&self,
path: &str,
interface: &str,
member: &str,
args: &[Value],
) -> Result<(), Error>
pub fn emit_signal( &self, path: &str, interface: &str, member: &str, args: &[Value], ) -> Result<(), Error>
Sourcepub fn request_name(&self, name: &str, flags: u32) -> Result<u32, Error>
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.
Sourcepub fn name_has_owner(&self, name: &str) -> bool
pub fn name_has_owner(&self, name: &str) -> bool
Whether some connection owns name; false when the bus cannot be asked.
Sourcepub fn on_signal<F>(&self, filter: SignalFilter, callback: F) -> SubscriptionId
pub fn on_signal<F>(&self, filter: SignalFilter, callback: F) -> SubscriptionId
Calls callback on the reader thread for every incoming signal that filter matches.
Sourcepub fn remove_signal_handler(&self, id: SubscriptionId)
pub fn remove_signal_handler(&self, id: SubscriptionId)
Removes a subscription made with on_signal.
Sourcepub fn export<F>(&self, path: &str, handler: F) -> Result<(), Error>
pub fn export<F>(&self, path: &str, handler: F) -> Result<(), Error>
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.