Struct async_rustbus::RpcConn

pub struct RpcConn { /* fields omitted */ }

RpcConn is used to create and interact with a DBus connection. It can be used to easily connect to either session (user) or system DBus daemons. RpcConn is thread-safe and can be used from within an Arc if desired.

Implementations

impl RpcConn

pub fn get_name(&self) -> &str

Returns the name assigned by the DBus daemon. This name was retreived using the org.freedesktop.DBus.Hello call when the connection was started.

pub async fn session_conn(with_fd: bool) -> Result<Self>

Connect to the system bus.

If with_fd is true then sending and receiving file descriptors is enabled for this connection.

Notes

• Like all the RpcConn constructors, this method handles sending the initial org.freedesktop.DBus.Hello message and handles the response.

Examples

use async_rustbus::RpcConn;
use async_rustbus::rustbus_core::message_builder::MessageBuilder;
let conn = RpcConn::system_conn(false).await.unwrap();
let mut msg = MessageBuilder::new().call("GetConnectionUnixProcessID")
    .at("org.freedesktop.DBus")
       .on("/org/freedesktop/DBus")
    .with_interface("org.freedesktop.DBus")
    .build();
msg.body.push_param(conn.get_name()).unwrap();
let res = conn.send_msg_w_rsp(&msg).await.unwrap().await.unwrap();
let pid: u32 = res.body.parser().get().unwrap();
assert_eq!(pid, std::process::id());

pub async fn system_conn(with_fd: bool) -> Result<Self>

Connect to the session (user) bus.

If with_fd is true then sending and receiving file descriptors is enabled for this connection.

Notes

• Like all the RpcConn constructors, this method handles sending the initial org.freedesktop.DBus.Hello message and handles the response.

Examples

use async_rustbus::RpcConn;
use async_rustbus::rustbus_core::message_builder::MessageBuilder;
let conn = RpcConn::system_conn(false).await.unwrap();
let mut msg = MessageBuilder::new().call("GetConnectionUnixProcessID")
    .at("org.freedesktop.DBus")
       .on("/org/freedesktop/DBus")
    .with_interface("org.freedesktop.DBus")
    .build();
msg.body.push_param(conn.get_name()).unwrap();
let res = conn.send_msg_w_rsp(&msg).await.unwrap().await.unwrap();
let pid: u32 = res.body.parser().get().unwrap();
assert_eq!(pid, std::process::id());

pub async fn connect_to_addr<P: AsRef<Path>, S: ToSocketAddrs, B: AsRef<[u8]>>(
    addr: &DBusAddr<P, S, B>,
    with_fd: bool
) -> Result<Self>

Connect to the given address.

This can be used to connect to a non-standard DBus daemon. If with_fd is true then sending and receiving file descriptors is enabled for this connection. In most instances users should use session_conn or system_conn to connecto to their local DBus instance.

Notes

• Like all the RpcConn constructors, this method handles sending the initial org.freedesktop.DBus.Hello message and handles the response.

Examples

use async_rustbus::{RpcConn, DBusAddr};
use async_rustbus::rustbus_core::message_builder::MessageBuilder;
let system_addr = DBusAddr::unix_path("/run/dbus/system_bus_socket");
let conn = RpcConn::connect_to_addr(&system_addr, false).await.unwrap();
let mut msg = MessageBuilder::new().call("GetConnectionUnixProcessID")
    .at("org.freedesktop.DBus")
       .on("/org/freedesktop/DBus")
    .with_interface("org.freedesktop.DBus")
    .build();
msg.body.push_param(conn.get_name()).unwrap();
let res = conn.send_msg_w_rsp(&msg).await.unwrap().await.unwrap();
let pid: u32 = res.body.parser().get().unwrap();
assert_eq!(pid, std::process::id());

pub async fn connect_to_path<P: AsRef<Path>>(
    path: P,
    with_fd: bool
) -> Result<Self>

Connect to the given Unix sockect path.

This can be used to connect to a non-standard DBus daemon. If with_fd is true then sending and receiving file descriptors is enabled for this connection. In most instances users should use session_conn or system_conn to connecto to their local DBus instance.

Notes

• Like all the RpcConn constructors, this method handles sending the initial org.freedesktop.DBus.Hello message and handles the response.

Examples

use async_rustbus::RpcConn;
use async_rustbus::rustbus_core::message_builder::MessageBuilder;
let conn = RpcConn::connect_to_path("/run/dbus/system_bus_socket", false).await.unwrap();
let mut msg = MessageBuilder::new().call("GetConnectionUnixProcessID")
    .at("org.freedesktop.DBus")
       .on("/org/freedesktop/DBus")
    .with_interface("org.freedesktop.DBus")
    .build();
msg.body.push_param(conn.get_name()).unwrap();
let res = conn.send_msg_w_rsp(&msg).await.unwrap().await.unwrap();
let pid: u32 = res.body.parser().get().unwrap();
assert_eq!(pid, std::process::id());

pub async fn send_msg(
    &self,
    msg: &MarshalledMessage
) -> Result<Option<impl Future<Output = Result<MarshalledMessage>> + '_>>

Make a DBus call to a remote service or send a signal.

This function returns a future nested inside a future. Awaiting the outer future sends the message out the DBus stream to the remote service. The inner future, returned by the outer, waits for the response from the remote service.

Notes

• If the message sent was a signal or has the NO_REPLY_EXPECTED flag set then the inner future will return immediatly when awaited.
• If two futures are simultanously being awaited (like via futures::future::join or across tasks) then outgoing order of messages is not guaranteed.
• If other incoming message are received before a response is received, then they will be processed by this future while awaiting. This processing may include placing messages in their correct queue or sending simple responses out the connection.

pub async fn send_msg_wo_rsp(&self, msg: &MarshalledMessage) -> Result<()>

Sends a signal or make a call to a remote service with the NO_REPLY_EXPECTED flag set.

Notes

• If multiple send futures are simultanously being awaited (like via futures::future::join or across tasks) then outgoing order of messages is not guaranteed.

Panics

• Panics if the message given expects a reply.

pub async fn send_msg_w_rsp(
    &self,
    msg: &MarshalledMessage
) -> Result<impl Future<Output = Result<MarshalledMessage>> + '_>

Make a call to a remote service.

msg must be a message the expects a call otherwise this method will panic.

Notes

• If multiple send futures are simultanously being awaited (like via futures::future::join or across tasks) then outgoing order of messages is not guaranteed.
• If other incoming message are received before a response is received, then they will be processed by this future while awaiting. This processing may include placing messages in their correct queue or sending simple responses out the connection.

Panics

• Panics if the message does not expect a reply, such as signals or calls with the NO_REPLY_EXPECTED set.

pub async fn insert_sig_match(&self, sig_match: &MatchRule) -> Result<()>

Add a match to retreive signals.

A org.freedesktop.DBus.AddMatch call is made to tell the DBus daemon to route matching signals to this connection. These signals are stored by the RpcConn and can be retreived by using the get_signal method. If a message is received that matches multiple sig_matches, then the message is associated with the most specific specific MatchRule. See MatchRule for more details.

Panics

• Panics if both the path and path_namespace matching parameters are used in the MatchRule.

Examples

use async_rustbus::{RpcConn, MatchRule};
let conn = RpcConn::session_conn(false).await.unwrap();
let rule = MatchRule::new()
    .sender("org.freedesktop.DBus")
    .interface("org.freedesktop.DBus")
    .member("NameOwnerChanged").clone();
conn.insert_sig_match(&rule).await.unwrap();
let owned = conn.request_name("example.name").await.unwrap();
if owned {
    let msg = conn.get_signal(&rule).await.unwrap();
    let (_, _, new_owner): (&str, &str, &str)  = msg.body.parser().get3().unwrap();
    assert_eq!(new_owner, conn.get_name());
}
conn.remove_sig_match(&rule).await.unwrap();

pub async fn remove_sig_match(&self, sig_match: &MatchRule) -> Result<()>

Stop the reception of messages matching sig_match

This method calls org.freedesktop.DBus.RemoveMatch to stop the reception of matching signals. Any messages already received that haven’t been retreived are lost. This method will return an InavalidInput if the MatchRule is not already present in the RpcConn.

Examples

See insert_sig_path for an example.

pub async fn get_signal(
    &self,
    sig_match: &MatchRule
) -> Result<MarshalledMessage>

Gets the next signal not filtered by the message filter.

Use the same sig_match used with insert_sig_match to wait for its associated signals. Signals with this connection as a destination are always sent to this connection regardless of if there is an matching MatchRule. If these signals are not filtered out and do not match a given filter they can be retreived uisng the default MatchRule.

Notes

• While awaiting for a matching signal, this future will process other incoming messages. This processing may include placing messages in their correct queue or sending simple responses out the connection.

Examples

See insert_sig_match for an example.

pub async fn get_call<'a, S, D>(&self, path: S) -> Result<MarshalledMessage> where
    S: TryInto<&'a ObjectPath, Error = D>,
    D: Debug, 

Gets the next call associated with the given path.

Use insert_call_path to setup the RpcConn for receiving calls. An InvalidInput error is returned if the path does not have an associated queue.

Notes

• While awaiting for a matching call, this future will process other incoming messages. This processing may include placing messages in their correct queue or sending simple responses out the connection.

pub async fn insert_call_path<'a, S, D>(
    &self,
    path: S,
    action: CallAction
) -> Result<(), D> where
    S: TryInto<&'a ObjectPath, Error = D>, 

Configure what action the RpcConn should take when receiving calls for a path or namespace.

See CallAction for details on what each action does. The default action before any insert_call_path calls is to drop all incoming messsage calls and reply with an error.

pub async fn get_call_path_action<'a, S: TryInto<&'a ObjectPath>>(
    &self,
    path: S
) -> Option<CallAction>

Get the action for a path.

Returns

Returns the action if there is one for that path. If there is no action for the given path or the path is invalid None is returned.

pub async fn get_call_recv<'a, S: TryInto<&'a ObjectPath>>(
    &self,
    path: S
) -> Option<CReceiver<MarshalledMessage>>

Get a receiver for the incoming call queue if there is one.

This receiver will produce calls from this path/namespace. Receiving messages from the Receiver doesn’t actually cause the RpcConn to do any work. It will only produce messages if another future from get_signal or get_call is being worked on. This method can be useful if you know that there are other tasks working using this RpcConn that will do the work of processing incoming messages.

pub async fn request_name(&self, name: &str) -> Result<bool>

Request a name from the DBus daemon.

Returns true if the name was successfully obtained or if it was already owned by this connection. otherwise false is returned (assuming an IO error did not occur). The DO_NOT_QUEUE flag is used with the request so if the name is not available, this connection will not be queued to own it in the future.

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

Release a name from the DBus daemon.

An Err is only returned on a IO error. If the name was not owned by the connection, or the name was invalid Ok is still returned.

Trait Implementations

impl AsRawFd for RpcConn

fn as_raw_fd(&self) -> RawFd

Extracts the raw file descriptor.