bus/README.md

   1 # Launcher for the accessibility bus
   2
   3 The communications mechanism for accessibility does not run through the user's session
   4 DBus; it runs in a separate bus just for accessibility purposes.  The accessibility
   5 interfaces for DBus are very chatty; using a separate bus prevents the main session bus
   6 from getting too much traffic.
   7
   8 Throughout this document we will distinguish between the **session bus** and the
   9 **accessibility bus**.
  10
  11 ## Who launches the accessibility bus?
  12
  13 This source directory `bus` contains a little daemon, `at-spi-bus-launcher`, which
  14 launches the **accessibility bus** and manages its lifetime according to the user's
  15 session.
  16
  17 The **accessibility bus** is just a separate instance of `dbus-daemon` or equivalent, like
  18 `dbus-broker`.  That bus allows communication using the accessibility interfaces defined
  19 in the `xml` directory in this repository.  It also has the accessibility registry —
  20 `registryd` in this repository, which claims the name `org.a11y.atspi.Registry` in that
  21 bus.
  22
  23 ## When does the accessibility bus get launched?
  24
  25 When a normal application starts up, it will want to find the **accesibility bus**, and
  26 then contact the accessibility registry in that bus (`registryd` in this repository) to
  27 inform the world that they are up and running.  Finding the accessibility bus can then be
  28 done on demand for normal applications, via the `GetAddress` method described below.
  29
  30 However, a screen reader is special: it needs to start up automatically during login, and
  31 immediatelly tell the accessibility registry (... via the **accessibility bus**) that it
  32 is running.  If you need a screen reader to use your computer, you cannot easily launch it
  33 by hand if there is no screen reader already running!
  34
  35 That is, if a screen reader is turned on — and we assume it will start up turned on for
  36 future sessions — we need to launch the **accessibility bus** unconditionally, not on
  37 demand, at session startup.  This is why `at-spi-dbus-bus.desktop`, described below, is an
  38 [XDG autostart][xdg-autostart] file which runs `at-spi-bus-launcher --launch-immediately`,
  39 but only if a certain GSettings key is turned on.
  40
  41 In summary, `at-spi-bus-launcher` will launch the **accessibility bus** under two situations:
  42
  43 * On demand via the `GetAddress` method; see below.
  44
  45 * Shortly after `at-spi-bus-launcher` starts up, if the gsettings key
  46   `org.gnome.desktop.interface toolkit-accessibility` is set to true, due to the
  47   `at-spi-dbus-bus.desktop` XDG autostart file.
  48
  49 * The gsettings key `org.gnome.desktop.a11y.applications screen-reader-enabled` is set to true.
  50
  51 ## Contents of this `bus` directory
  52
  53 This `bus` source directory has a configuration file for the `dbus-daemon` which will run
  54 as the **accessibility bus**, and a helper daemon called `at-spi-bus-launcher`, which actually
  55 starts that bus and makes its address visible to the user's session.  The files are as follows:
  56
  57 * `accessibility.conf.in` - template for the configuration for the accessibility bus,
  58   which gets installed in `$(datadir)/defaults/at-spi2/accessibility.conf`.
  59
  60 * `at-spi-bus-launcher.c` - See [`at-spi-bus-launcher`](#at-spi-bus-launcher) below.
  61
  62 * `at-spi-dbus-bus.service.in` - template for a systemd user service to start `at-spi-bus-launcher`.
  63
  64 * `org.a11y.Bus.service.in` - template for a DBus user service to start `at-spi-bus-launcher`.
  65
  66 * `at-spi-dbus-bus.desktop.in` - template for a XDG autostart file to start
  67   `at-spi-bus-launcher` at session startup, only if the `org.gnome.desktop.interface
  68   toolkit-accessibility` GSettings key is turned on.
  69
  70 * `00-at-spi` - script to set the `AT_SPI_BUS` property on the X root window, for
  71   Wayland-based systems where XWayland is started on demand.  That X window property is an
  72   alternative way of finding the address of the **accessibility bus**.
  73
  74 ## at-spi-bus-launcher
  75
  76 This is a tiny daemon which registers a service in the normal **session bus**, and which
  77 can then be used to query the address of the actual **accessibility bus**.  The daemon
  78 claims ownership of the `org.a11y.Bus` name in the **session bus**, and exports a
  79 single object, `/org/a11y/bus`, with two interfaces:
  80
  81 * `org.a11y.Bus` - has a single `GetAddress` method, which returns the address of the
  82   actual **accessibility bus**.  Accessibility clients must use this address when creating
  83   their initial DBus connection.
  84
  85 * `org.a11y.Status` - has properties to query whether the **accessibility bus** is enabled
  86   and whether a screen reader is running.
  87
  88 `at-spi-bus-launcher` starts the separate `dbus-daemon` (or `dbus-broker` equivalent) for
  89 the **accessibility bus** on demand.  The following actions can cause it to launch:
  90
  91 * Calling the `GetAddress` method.  The daemon gets launched and queried for its address;
  92   the method returns that.  This is the normal way to start the accessibility bus.
  93
  94 * If `at-spi-bus-launcher` was run with the `--launch-immediately` option, the
  95   accessibility bus launches as soon as `at-spi-bus-launcher` is able to claim ownership
  96   of the `org.a11y.Bus` name in the session bus.  This is intended for session startup.
  97
  98 [xdg-autostart]: https://specifications.freedesktop.org/autostart-spec/autostart-spec-latest.html