An essential purpose of BrlAPI is to manage concurrent access to the braille display between the brltty daemon and applications. This concurrency is managed "per Tty". We first describe this with a flat view, and then consider Tty hierarchy.
Let's first describe how things work with the simple case of a single series of Virtual Ttys (VTs), the linux console for instance.
As described in General Description, before being able to write output, a BrlAPI client has to "get" a tty, i.e. it sends to the BrlAPI server the number of the linux' Virtual Tty on which it is running. The BrlAPI server uses this information so as to know which client's output should be shown on the braille display, according to the focus teller's information.
Let's say some client A is running on VT 2. It "got" VT 2 and wrote some output on its BrlAPI connection. The focus teller is brltty here: it always tells to the BrlAPI server which VT is currently shown on the screen and gets usual keyboard presses (it is "active").
Let's say VT 1 is active, then the BrlAPI server shows brltty's output on the braille display. I.e. the usual brltty screen reading appears. Moreover, when braille keys are pressed, they are passed to brltty, so that usual screen reading can be performed. When the user switches to VT 2, brltty (as focus teller) tells it to the BrlAPI server, which then remembers that client A has got it and has produced some output. The server then displays this output on the braille display. Note that A doesn't need to re-submit its output: the server had recorded it so as to be able to show it as soon as the focus switches to VT 2. Whenever some key of the braille device is pressed, BrlAPI looks whether it is in the list of keys that client A said to be of his interest. If it is, it is passed to A (and not to brltty). If it isn't, it is passed to brltty (and not to A).
As a consequence, whenever clients get and release Ttys and the user switches between Ttys, either the brltty screen reading or the client's output is automatically shown according to rather natural rules.
Let's look at VT 2 by itself. What is shown on the braille display can be seen as the result of a pile of two paper sheets. brltty is represented by the bottom sheet on which its screen reading is written, and client A by the top sheet on which its output is written. A's sheet hence "covers" brltty's sheet: A's output "mask" brltty's screen reading.
A may yet want to temporarily let brltty's screen reading appear on VT 2, while still receiving some key presses, for instance. For this, it sends a "void" write. The server then clears the recorded output for this connection (in the sheet representation, the sheet becomes "transparent"). As a consequence, brltty's output is automatically shown (by transparency in the sheet representation), just like if A had released the Tty.
Keypresses are handled in a similar way: A's desire to get key presses is satisfied first before brltty.
Let's say some other client B (probably launched by A) also gets VT 2 and outputs some text on its BrlAPI connection. This adds a third sheet, on top of the two previous ones. It means that the BrlAPI server will show B's output on the braille device. If A then outputs some text, the server will record it (on A's sheet which hence becomes opaque again), but it won't be displayed on the braille device, since B's sheet is still at the top and opaque (i.e. with some text on it). But if B issues a void write, the server clears its ouput buffer (i.e. B's sheet becomes transparent), and as a result A's output appear on the braille display (by transparency through B's sheet).
The sheet order is by default determined by the Tty "get"ting order. Clients can however change their priority (which by default is 50) to a higher value in order to show up higher in the pile, or to a lower value in order to hide lower in the pile.
Now, what happens when running some screen program on, say, VT 3? It emulates a series of Ttys, whose output actually appear on the same VT 3. That's where a hierarchy level appears: the focus information is not only the VT number but also, in the case of VT 3, which screen window is active. This hence forms a tree of Ttys: the "root" being the vga driver's output, whose sons are VTs, and VT 3 has the screen windows as sons. Brltty is a focus teller for the root, screen will have to be a focus teller for VT 3. Screen should then get VT 3, not display anything (so that the usual brltty screen reading will be shown by transparency), and tell the BrlAPI server which screen window is active (at startup and at each window switch). This is not implemented directly in screen yet, but this may be achieved via a second brltty daemon running the Screen driver (but it isn't yet able to get the current window number though) and the BrlAPI driver.
A BrlAPI client C running in some screen window number 1 would
then have to get the Tty path "VT 3 then window 1", which is merely expressed
as "3 1". The window number is available in the WINDOW environment
variable, set by screen. The VT number, which actually represents the "path
to screen's output" should be available in the WINDOWPATH environment
variable, also set by screen. The client can thus merely concatenate the
content of WINDOWPATH (which could hold many levels of window numbers) and
of WINDOW and give the result as tty path to the BrlAPI server, which
then knows precisely where the client's usual output resides. In practice,
applications just need to call brlapi_enterTtyMode(BRLAPI_TTY_DEFAULT), and
the the BrlAPI client library will automatically perform all that.
Whenever the user switches to VT 3, the BrlAPI server remembers the window that screen told to be active. If it was window 1, it then displays C's output (if any). Else brltty's usual screen reading is shown. Of course, several clients may be run in window 1 as well, and the "sheet pile" mecanism applies: brltty's sheet first (at the root of the Ttys tree), then screen's sheet (which is transparent, on VT 3), then C's sheet (on window 1 of VT 3), then other clients' sheets (on the same window).
Ttys are hence organized in a tree, each client adding its sheet at some tty in the tree.
Let's say some X server is running on VT 7 of a Linux system. Xorg's xinit
and xdm commands automatically set the X session's WINDOWPATH
environment variable to "7", so that X11 BrlAPI clients started from
the session just need to call brlapi_enterTtyMode(xid) where xid
is the X-window ID of the window of the client. The BrlAPI library
will automatically prepend the content of WINDOWPATH to it.
For text-based BrlAPI clients running in an xterm (which should just call
brlapi_enterTtyMode(BRLAPI_TTY_DEFAULT) as explained in the previous
section), BrlAPI detects the window id thanks to the WINDOWID variable
set by xterm.
Screen readers are not bound to a particular window, so they should call
brlapi_enterTtyModeWithPath(NULL, 0) to let the BrlAPI library only
send the content of WINDOWPATH, expressing that screen readers take the
whole tty. The user should notably launch xbrlapi, which is a focus
teller for X-window as well as a keyboard simulator (brltty can't reliably
simulate them at the kernel level in such situation). For accessing AT-SPI
contents (like gnome or kde applications), Orca should also be launched. For
accessing AT-SPI terminals (like gnome-terminal) in the same way as in the
console, a second brltty daemon running the at-spi screen driver and the
BrlAPI driver can also be launched. All three would get the VT of the
X session, in that order (for now): xbrlapi first, then orca and
brltty at last. When the X focus is on an AT-SPI terminal, brltty
will hence be able to grab the braille display and key presses. Else orca
would get them. And xbrlapi would finally get remaining key presses and
simulate them.
Note: old versions of xinit, xdm, kdm or gdm do not
automatically set the WINDOWPATH variable. The user can set it by hand in
his ~/.xsession, ~/.xinitrc, ~/.gdmrc... to "7"
Note: some Operating Systems like Solaris do not have VTs. In that case
WINDOWPATH is empty or not even set. Everything explained above still
work fine.
Several programs allow detaching: screen and VNC for instance. In such situation, an intermediate BrlAPI server should be run for each such session. Clients would connect to it, and it would prepend the "current tty" path on the fly while forwarding things to the root BrlAPI server. This intermediate server is yet to be written (but it is actually relatively close to be).