[−][src]Struct zbus::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
.
For lower-level handling of the connection (such as nonblocking socket handling), see the
documentation of the new_authenticated_unix
constructor.
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.
NB: If you want to send and receive messages from multiple threads at the same time, it's usually better to create unique connections for each thread. Otherwise you can end up with deadlocks. For example, if one thread tries to send a message on a connection, while another is waiting to receive a message on the bus, the former will block until the latter receives a message.
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
[src]
pub fn new_unix_client(stream: UnixStream, bus_connection: bool) -> Result<Self>
[src]
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>
[src]
Create a Connection
to the session/user message bus.
pub fn new_system() -> Result<Self>
[src]
Create a Connection
to the system-wide message bus.
pub fn new_for_address(address: &str, bus_connection: bool) -> Result<Self>
[src]
Create a Connection
for the given D-Bus address.
pub fn new_unix_server(stream: UnixStream, guid: &Guid) -> Result<Self>
[src]
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
[src]
Max number of messages to queue.
pub fn set_max_queued(self, max: usize) -> Self
[src]
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
[src]
The server's GUID.
pub fn unique_name(&self) -> Option<&str>
[src]
The unique name as assigned by the message bus or None
if not a message bus connection.
pub fn receive_message(&self) -> Result<Message>
[src]
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 the connection is in non-blocking mode, this will return a
WouldBlock
error instead of blocking. If there are pending messages in the queue, the
first one from the queue is returned instead of attempting to read the connection.
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 receive_specific<P>(&self, predicate: P) -> Result<Message> where
P: Fn(&Message) -> Result<bool>,
[src]
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>
[src]
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 flush(&self) -> Result<()>
[src]
Flush pending outgoing messages to the server
This method is only useful if the connection is in non-blocking mode. It will write as many pending outgoing messages as possible to the socket.
It will return Ok(())
if all messages could be sent, and error otherwise. A
WouldBlock
error means that the internal buffer of the connection transport is
full, and you need to wait for write-readiness before calling this method again.
If the connection is in blocking mode, this will return Ok(())
and do nothing.
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,
[src]
&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
.
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,
[src]
&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,
[src]
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,
[src]
&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> + Send>
)
[src]
&mut self,
handler: Box<dyn FnMut(Message) -> Option<Message> + Send>
)
You shouldn't need this anymore since Connection queues messages
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)
[src]
You shouldn't need this anymore since Connection queues messages
Reset the default message handler.
Remove the previously set message handler from set_default_message_handler
.
pub fn new_authenticated_unix(auth: Authenticated<UnixStream>) -> Self
[src]
Create a Connection
from an already authenticated unix socket
This method can be used in conjunction with ClientHandshake
or ServerHandshake
to handle
the initial handshake of the D-Bus connection asynchronously. The Authenticated
argument required
by this method is the result provided by these handshake utilities.
If the aim is to initialize a client bus connection, you need to send the client hello and assign
the resulting unique name using set_unique_name
before doing anything else.
pub fn set_unique_name(&self, name: String) -> Result<(), String>
[src]
Sets the unique name for this connection
This method should only be used when initializing a client bus connection with
new_authenticated_unix
. Setting the unique name to anything other than the return value of the bus
hello is a protocol violation.
Returns and error if the name has already been set.
pub fn is_bus(&self) -> bool
[src]
Checks if self
is a connection to a message bus.
This will return false
for p2p connections.
Trait Implementations
impl AsRawFd for Connection
[src]
impl Clone for Connection
[src]
pub fn clone(&self) -> Connection
[src]
pub fn clone_from(&mut self, source: &Self)
1.0.0[src]
impl Debug for Connection
[src]
Auto Trait Implementations
impl RefUnwindSafe for Connection
[src]
impl Send for Connection
[src]
impl Sync for Connection
[src]
impl Unpin for Connection
[src]
impl UnwindSafe for Connection
[src]
Blanket Implementations
impl<T> Any for T where
T: 'static + ?Sized,
[src]
T: 'static + ?Sized,
impl<T> Borrow<T> for T where
T: ?Sized,
[src]
T: ?Sized,
impl<T> BorrowMut<T> for T where
T: ?Sized,
[src]
T: ?Sized,
pub fn borrow_mut(&mut self) -> &mut T
[src]
impl<T> From<T> for T
[src]
impl<T, U> Into<U> for T where
U: From<T>,
[src]
U: From<T>,
impl<T> ToOwned for T where
T: Clone,
[src]
T: Clone,
type Owned = T
The resulting type after obtaining ownership.
pub fn to_owned(&self) -> T
[src]
pub fn clone_into(&self, target: &mut T)
[src]
impl<T, U> TryFrom<U> for T where
U: Into<T>,
[src]
U: Into<T>,
type Error = Infallible
The type returned in the event of a conversion error.
pub fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>
[src]
impl<T, U> TryInto<U> for T where
U: TryFrom<T>,
[src]
U: TryFrom<T>,