1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
|
# 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][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`](#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.
[xdg-autostart]: https://specifications.freedesktop.org/autostart-spec/autostart-spec-latest.html
|
