Skip to content

Latest commit

 

History

History
98 lines (69 loc) · 5.08 KB

README.md

File metadata and controls

98 lines (69 loc) · 5.08 KB

Launcher for the accessibility bus

The communications mechanism for accessibility does not run through the user's session DBus; it runs in a separate bus just for accessibility purposes. The accessibility interfaces for DBus are very chatty; using a separate bus prevents the main session bus from getting too much traffic.

Throughout this document we will distinguish between the session bus and the accessibility bus.

Who launches the accessibility bus?

This source directory bus contains a little daemon, at-spi-bus-launcher, which launches the accessibility bus and manages its lifetime according to the user's session.

The accessibility bus is just a separate instance of dbus-daemon or equivalent, like dbus-broker. That bus allows communication using the accessibility interfaces defined in the xml directory in this repository. It also has the accessibility registry — registryd in this repository, which claims the name org.a11y.atspi.Registry in that bus.

When does the accessibility bus get launched?

When a normal application starts up, it will want to find the accesibility bus, and then contact the accessibility registry in that bus (registryd in this repository) to inform the world that they are up and running. Finding the accessibility bus can then be done on demand for normal applications, via the GetAddress method described below.

However, a screen reader is special: it needs to start up automatically during login, and immediatelly tell the accessibility registry (... via the accessibility bus) that it is running. If you need a screen reader to use your computer, you cannot easily launch it by hand if there is no screen reader already running!

That is, if a screen reader is turned on — and we assume it will start up turned on for future sessions — we need to launch the accessibility bus unconditionally, not on demand, at session startup. This is why at-spi-dbus-bus.desktop, described below, is an XDG autostart file which runs at-spi-bus-launcher --launch-immediately, but only if a certain GSettings key is turned on.

In summary, at-spi-bus-launcher will launch the accessibility bus under two situations:

  • On demand via the GetAddress method; see below.

  • Shortly after at-spi-bus-launcher starts up, if the gsettings key org.gnome.desktop.interface toolkit-accessibility is set to true, due to the at-spi-dbus-bus.desktop XDG autostart file.

  • The gsettings key org.gnome.desktop.a11y.applications screen-reader-enabled is set to true.

Contents of this bus directory

This bus source directory has a configuration file for the dbus-daemon which will run as the accessibility bus, and a helper daemon called at-spi-bus-launcher, which actually starts that bus and makes its address visible to the user's session. The files are as follows:

  • accessibility.conf.in - template for the configuration for the accessibility bus, which gets installed in $(datadir)/defaults/at-spi2/accessibility.conf.

  • at-spi-bus-launcher.c - See at-spi-bus-launcher below.

  • at-spi-dbus-bus.service.in - template for a systemd user service to start at-spi-bus-launcher.

  • org.a11y.Bus.service.in - template for a DBus user service to start at-spi-bus-launcher.

  • at-spi-dbus-bus.desktop.in - template for a XDG autostart file to start at-spi-bus-launcher at session startup, only if the org.gnome.desktop.interface toolkit-accessibility GSettings key is turned on.

  • 00-at-spi - script to set the AT_SPI_BUS property on the X root window, for Wayland-based systems where XWayland is started on demand. That X window property is an alternative way of finding the address of the accessibility bus.

at-spi-bus-launcher

This is a tiny daemon which registers a service in the normal session bus, and which can then be used to query the address of the actual accessibility bus. The daemon claims ownership of the org.a11y.Bus name in the session bus, and exports a single object, /org/a11y/bus, with two interfaces:

  • org.a11y.Bus - has a single GetAddress method, which returns the address of the actual accessibility bus. Accessibility clients must use this address when creating their initial DBus connection.

  • org.a11y.Status - has properties to query whether the accessibility bus is enabled and whether a screen reader is running.

at-spi-bus-launcher starts the separate dbus-daemon (or dbus-broker equivalent) for the accessibility bus on demand. The following actions can cause it to launch:

  • Calling the GetAddress method. The daemon gets launched and queried for its address; the method returns that. This is the normal way to start the accessibility bus.

  • If at-spi-bus-launcher was run with the --launch-immediately option, the accessibility bus launches as soon as at-spi-bus-launcher is able to claim ownership of the org.a11y.Bus name in the session bus. This is intended for session startup.