Struct AccessibilityConnection 

pub struct AccessibilityConnection { /* private fields */ }

A connection to the at-spi bus

Implementations

impl AccessibilityConnection

pub async fn new() -> AtspiResult<Self>

Open a new connection to the bus

Errors

May error when a bus is not available, or when the accessibility bus (AT-SPI) can not be found.

pub async fn from_address(bus_addr: Address) -> AtspiResult<Self>

Returns an AccessibilityConnection, a wrapper for the RegistryProxy; a handle for the registry provider on the accessibility bus.

You may want to call this if you have the accessibility bus address and want a connection with a convenient async event stream provisioning.

Without address, you will want to call open, which tries to obtain the accessibility bus’ address on your behalf.

Errors

RegistryProxy is configured with invalid path, interface or destination

pub fn event_stream(&self) -> impl Stream<Item = Result<Event, AtspiError>>

Stream yielding all Event types.

Monitor this stream to be notified and receive events on the a11y bus.

Example

Basic use:

use atspi_connection::AccessibilityConnection;
use enumflags2::BitFlag;
use atspi_connection::common::events::{ObjectEvents, object::StateChangedEvent};
use zbus::{fdo::DBusProxy, MatchRule, message::Type as MessageType};
use atspi_connection::common::events::Event;


    let atspi = AccessibilityConnection::new().await?;
    atspi.register_event::<ObjectEvents>().await?;

    let mut events = atspi.event_stream();
    std::pin::pin!(&mut events);

    while let Some(Ok(ev)) = events.next().await {
        // Handle Object events
       if let Ok(event) = StateChangedEvent::try_from(ev) {
         // do something else here
       } else { continue }
    }

pub async fn add_match_rule<T: DBusMatchRule>(&self) -> Result<(), AtspiError>

Registers an events as defined in atspi_common::events.
This function registers a single event, like so:

Example

use atspi_connection::common::events::object::StateChangedEvent;
let connection = atspi_connection::AccessibilityConnection::new().await.unwrap();
connection.register_event::<StateChangedEvent>().await.unwrap();

Errors

This function may return an error if a zbus::Error is caused by all the various calls to zbus::fdo::DBusProxy and zbus::MatchRule::try_from.

pub async fn remove_match_rule<T: DBusMatchRule>( &self, ) -> Result<(), AtspiError>

Deregisters an event as defined in atspi_common::events.
This function registers a single event, like so:

Example

use atspi_connection::common::events::object::StateChangedEvent;
let connection = atspi_connection::AccessibilityConnection::new().await.unwrap();
connection.add_match_rule::<StateChangedEvent>().await.unwrap();
connection.remove_match_rule::<StateChangedEvent>().await.unwrap();

Errors

This function may return an error if a zbus::Error is caused by all the various calls to zbus::fdo::DBusProxy and zbus::MatchRule::try_from.

pub async fn add_registry_event<T: RegistryEventString>( &self, ) -> Result<(), AtspiError>

Add a registry event. This tells accessible applications which events should be forwarded to the accessibility bus. This is called by Self::register_event.

Example

use atspi_connection::common::events::object::StateChangedEvent;
let connection = atspi_connection::AccessibilityConnection::new().await.unwrap();
connection.add_registry_event::<StateChangedEvent>().await.unwrap();
connection.remove_registry_event::<StateChangedEvent>().await.unwrap();

Errors

May cause an error if the DBus method atspi_proxies::registry::RegistryProxy::register_event fails.

pub async fn remove_registry_event<T: RegistryEventString>( &self, ) -> Result<(), AtspiError>

Remove a registry event. This tells accessible applications which events should be forwarded to the accessibility bus. This is called by Self::deregister_event. It may be called like so:

Example

use atspi_connection::common::events::object::StateChangedEvent;
let connection = atspi_connection::AccessibilityConnection::new().await.unwrap();
connection.add_registry_event::<StateChangedEvent>().await.unwrap();
connection.remove_registry_event::<StateChangedEvent>().await.unwrap();

Errors

May cause an error if the DBus method RegistryProxy::deregister_event fails.

pub async fn register_event<T: RegistryEventString + DBusMatchRule>( &self, ) -> Result<(), AtspiError>

This calls Self::add_registry_event and Self::add_match_rule, two components necessary to receive accessibility events.

Errors

This will only fail if [Self::add_registry_event[ or Self::add_match_rule fails.

pub async fn deregister_event<T: RegistryEventString + DBusMatchRule>( &self, ) -> Result<(), AtspiError>

This calls Self::remove_registry_event and Self::remove_match_rule, two components necessary to receive accessibility events.

Errors

This will only fail if Self::remove_registry_event or Self::remove_match_rule fails.

pub fn connection(&self) -> &Connection

Shorthand for a reference to the underlying zbus::Connection

pub async fn send_event<'a, T>(&self, event: T) -> Result<(), AtspiError>

where T: DBusMember + DBusInterface + EventProperties + MessageConversion<'a>,

Send an event over the accessibility bus. This converts the event into a zbus::Message using the DBusMember + DBusInterface trait.

Errors

This will only fail if:

1. zbus::Message fails at any point, or
2. sending the event fails for some reason.

Both of these conditions should never happen as long as you have a valid event.

pub async fn root_accessible_on_registry( &self, ) -> Result<AccessibleProxy<'_>, AtspiError>

Get the root accessible object from the atspi registry; This semantically represents the root of the accessibility tree and can be used for tree traversals.

It may be called like so:

Example

use atspi_connection::AccessibilityConnection;
use zbus::proxy::CacheProperties;
let connection = atspi_connection::AccessibilityConnection::new().await.unwrap();
let root = connection.root_accessible_on_registry().await.unwrap();
let children = root.get_children().await;
assert!(children.is_ok());

Errors

This will fail if a dbus connection cannot be established when trying to connect to the registry

Panics

This will panic if the default_service is not set on the RegistryProxy, which should never happen.

Methods from Deref<Target = RegistryProxy<'static>>

pub fn inner(&self) -> &Proxy<'p>

The reference to the underlying zbus::Proxy.

pub async fn deregister_event(&self, event: &str) -> Result<(), Error>

DeregisterEvent method

pub async fn registered_events( &self, ) -> Result<Vec<(OwnedBusName, String)>, Error>

GetRegisteredEvents method

pub async fn register_event(&self, event: &str) -> Result<(), Error>

RegisterEvent method

Trait Implementations

impl Clone for AccessibilityConnection

fn clone(&self) -> AccessibilityConnection

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for AccessibilityConnection

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

Formats the value using the given formatter.

impl Deref for AccessibilityConnection

type Target = RegistryProxy<'static>

The resulting type after dereferencing.

fn deref(&self) -> &Self::Target

Dereferences the value.

impl P2P for AccessibilityConnection

async fn object_as_accessible( &self, obj: &ObjectRefOwned, ) -> AtspiResult<AccessibleProxy<'_>>

Returns a P2P connected AccessibleProxy for the object, if available.
If the application does not support P2P, an AccessibleProxy with a bus connection is returned.

Examples

use zbus::names::UniqueName;
use zbus::zvariant::ObjectPath;
use atspi_proxies::accessible::AccessibleProxy;
use atspi_common::ObjectRef;
use atspi_connection::{P2P, Peer};
use atspi_connection::AccessibilityConnection;

let conn = AccessibilityConnection::new().await.unwrap();

let name = UniqueName::from_static_str_unchecked(":1.1");
let path = ObjectPath::from_static_str_unchecked("/org/freedesktop/accessible/root");

let object_ref = ObjectRef::new_owned(name, path);
let accessible_proxy = conn.object_as_accessible(&object_ref).await;
assert!(
   accessible_proxy.is_ok(),
   "Failed to get accessible proxy: {:?}",
   accessible_proxy.err()
);

Handling ObjectRef::Null case:

use atspi_proxies::accessible::AccessibleProxy;
use atspi_common::{AtspiError, ObjectRef, ObjectRefOwned};
use atspi_connection::P2P;
use atspi_connection::AccessibilityConnection;

let conn = AccessibilityConnection::new().await.unwrap();
let object_ref = ObjectRef::Null;
let object_ref = ObjectRefOwned::new(object_ref); // Assume we received this from `Accessible.Parent`

let res = conn.object_as_accessible(&object_ref).await;
match res {
    Ok(proxy) => {
        // Use the proxy
        let _proxy: AccessibleProxy<'_> = proxy;
    }
    Err(AtspiError::NullRef(_msg)) => {
        // Handle null-reference case
    }
    Err(_other) => {
        // Handle other error types
    }
}

Errors

If the method is called with a null-reference ObjectRef, it will return an AtspiError::NullRef. Users should ensure that the ObjectRef is non-null before calling this method or handle the result. If the AccessibleProxy cannot be created, or if the object path is invalid.

Note

This function will first try to find a Peer with a P2P connection

async fn bus_name_as_root_accessible( &self, name: &BusName<'_>, ) -> AtspiResult<AccessibleProxy<'_>>

Returns a P2P connected AccessibleProxy to the root accessible object for the given bus name if available.
If the P2P connection is not available, it returns an AccessibleProxy with a bus connection.

Examples

use zbus::names::BusName;
use atspi_proxies::accessible::AccessibleProxy;
use atspi_common::ObjectRef;
use atspi_connection::{AccessibilityConnection, P2P};

  let conn = AccessibilityConnection::new().await.unwrap();
  let bus_name = BusName::from_static_str("org.a11y.atspi.Registry").unwrap();
  let _accessible_proxy = conn.bus_name_as_root_accessible(&bus_name).await.unwrap();
  // Use the accessible proxy as needed

Errors

In case of an invalid connection or object path.

fn peers(&self) -> Arc<Mutex<Vec<Peer>>>

Get the currently connected P2P capable peers.

Examples

use atspi_connection::AccessibilityConnection;
use atspi_connection::{P2P, Peer};

  let conn = AccessibilityConnection::new().await.unwrap();
  let locked_peers = conn.peers();
  let peers = locked_peers.lock().expect("lock already held by current thread");
  for peer in &*peers {
      println!("Peer: {} at {}", peer.unique_name(), peer.socket_address());
  }

fn get_peer(&self, bus_name: &BusName<'_>) -> Option<Peer>

Returns a Peer by its bus name.

Examples

use atspi_connection::{AccessibilityConnection, P2P, Peer};
use zbus::names::BusName;

  let a11y = AccessibilityConnection::new().await.unwrap();
  let bus_name = BusName::from_static_str(":1.42").unwrap();
  let peer: Option<Peer> = a11y.get_peer(&bus_name);