BrlAPI Reference manual
Sébastien Hinderer <Sebastien.Hinderer@ens-lyon.org>
Samuel Thibault <Samuel.Thibault@ens-lyon.org>
V1.4, December 2006
This document describes BrlAPI.
______________________________________________________________________
Table of Contents
1. Introduction
1.1 Concepts
1.2 How to read this manual
2. General description of BrlAPI
2.1 Historical notes.
2.2 Why BrlAPI is part of brltty .
2.3 How it works.
2.3.1 Connection.
2.3.2 Authorization.
2.3.3 Real use of the braille terminal.
2.3.3.1 Braille display and braille key presses processing.
2.3.3.2 Raw mode.
2.3.3.3 Suspend Mode.
2.3.3.4 Remarks.
2.3.4 Disconnection.
3. Concurrency management between BrlAPI clients
3.1 VT switching
3.2 A pile of "paper sheets"
3.3 Hierarchy
3.4 The X-window case
3.5 Detaching
4. Installation and configuration of BrlAPI
5. Library description
5.1 Connecting to BrlAPI
5.2 Getting driver name
5.3 Getting display size
5.4 Entering raw mode, immediately leaving raw mode.
5.5 Getting tty control
5.6 Writing something on the display
5.7 Waiting for a key press
5.8 Understanding commands
5.9 Leaving tty control
5.10 Disconnecting from BrlAPI
5.11 Putting everything together...
6. Writing ( BrlAPI -compliant) drivers for brltty
6.1 Overview of the driver's structure
6.2 Basic driver structure
6.3 Enhancements for BrlAPI
6.3.1 Reading braille key codes
6.3.1.1 Remarks
6.3.2 Exchanging raw data packets
6.3.2.1 Remarks.
7. Protocol reference
7.1 Reliable packet transmission channel
7.2 Responses from the server
7.3 Operating modes
7.4 Details for each type of packet
7.4.1 BRLAPI_PACKET_VERSION This must be the first packet ever
transmitted from the server to the client and from the
client to the server. The server sends one first for
letting the client know its protocol version. Data is an
integer indicating the protocol version. Then client must
then respond the same way for giving its version. If the
protocol version can't be handled by the server, a
BRLAPI_ERROR_PROTOCOL_VERSION error packet is returned and
the connection is closed.
7.4.2 BRLAPI_PACKET_AUTH
7.4.3 BRLAPI_PACKET_GETDRIVERID (see brlapi_getDriverId() )
7.4.4 BRLAPI_PACKET_GETDRIVERNAME (see brlapi_getDriverName() )
7.4.5 BRLAPI_PACKET_GETDISPLAYSIZE (see brlapi_getDisplaySize() )
7.4.6 BRLAPI_PACKET_ENTERTTYMODE (see brlapi_enterTtyMode() and
brlapi_enterTtyModeWithPath() )
7.4.7 BRLAPI_PACKET_KEY (see brlapi_readKey() )
7.4.8 BRLAPI_PACKET_SETFOCUS (see brlapi_setFocus() )
7.4.9 BRLAPI_PACKET_LEAVETTYMODE (see brlapi_leaveTtyMode() )
7.4.10 BRLAPI_PACKET_IGNOREKEYRANGE and
BRLAPI_PACKET_ACCEPTKEYRANGE (see brlapi_ignoreKeyRange()
and brlapi_acceptKeyRange() )
7.4.11 BRLAPI_PACKET_WRITE (see brlapi_write() )
7.4.12 BRLAPI_PACKET_ENTERRAWMODE (see brlapi_enterRawMode() )
7.4.13 BRLAPI_PACKET_LEAVERAWMODE (see brlapi_leaveRawMode() )
7.4.14 BRLAPI_PACKET_PACKET (see brlapi_sendRaw() and
brlapi_recvRaw() )
7.4.15 BRLAPI_PACKET_SUSPENDDRIVER (see brlapi_suspendDriver() )
______________________________________________________________________
11.. IInnttrroodduuccttiioonn
_B_r_l_A_P_I is a service provided by the _b_r_l_t_t_y daemon.
Its purpose is to allow programmers to write applications that take
advantage of a braille terminal in order to deliver a blind user
suitable information for his/her specific needs.
While an application communicates with the braille terminal,
everything _b_r_l_t_t_y sends to the braille terminal in the application's
console is ignored, whereas each piece of data coming from the braille
terminal is sent to the application, rather than to _b_r_l_t_t_y.
11..11.. CCoonncceeppttss
All throughout this manual, a few terms will be used which are either
specific to braille terminals, or introduced because of _B_r_l_A_P_I. They
are defined below. Taking a few minutes to go through this glossary
will save a lot of time and questions later.
AAuutthhoorriizzaattiioonn kkeeyy
A file containing arbitrary data, that has to be sent to the
server by the client, to prove it is allowed to establish a
connection and then control the braille terminal.
BBrraaiillllee ddiissppllaayy
The small screen on the braille terminal that is able to display
braille text.
BBrraaiillllee kkeeyybbooaarrdd
The keyboard of the braille terminal.
BBrraaiillllee tteerrmmiinnaall
A computer designed to display text in braille. In this case,
the text is supposed to come from another computer running Linux
or any other Unix system.
BBrrllttttyy
The background process that gives a blind person access to the
console screen thanks to a braille terminal or speech
synthetizer.
CClliieenntt
An application designed to handle a braille terminal thanks to
_B_r_l_A_P_I.
CCoommmmaanndd
A code returned by the driver, indicating an action to do, for
instance "go to previous line", "go to next line", etc.
DDrriivveerr
A library that has functions to communicate with a braille
terminal. Basically, a driver has functions to open
communication with the braille terminal, close the
communication, write on the braille display, and read keypresses
from the braille keyboard, plus some special functions that will
be described in detail in this manual.
KKeeyy
A code that is returned by the driver when a key is pressed.
This is different from a command, because the command concept is
driver-independent (all drivers use the same command codes -
those defined by _b_r_l_t_t_y), whereas codes used for returning
keypresses may vary between drivers.
BBrrllAAPPII''ss LLiibbrraarryy
This library helps clients to connect and use _B_r_l_A_P_I's server
thanks to a series of brlapi_-prefixed functions.
PPaacckkeett
A sequence of bytes making up the atomic unit in communications,
either between braille drivers and braille terminals or between
the server and clients.
RRaaww mmooddee
Mode in which the client application exchanges packets with the
driver. Normal operations like sending text for display or
reading keypresses are not available in this mode. It lets
applications take advantage of advanced functionalities of the
driver's communication protocol.
SSeerrvveerr
The part of _b_r_l_t_t_y that controls incoming connections and
communication between clients and braille drivers.
SSuussppeenndd mmooddee
Mode in which the server keeps the device driver closed, so that
the client can connect directly to the device.
TTttyy
Synonym for console, terminal, ... Linux' console consist of
several Virtual Ttys (VTs). The screen program's windows also
are Ttys. X-window system's xterms emulate Ttys as well.
11..22.. HHooww ttoo rreeaadd tthhiiss mmaannuuaall
This manual is split in five parts.
````GGeenneerraall ddeessccrriippttiioonn''''
Describes more precisely what _B_r_l_A_P_I is and how it works in
collaboration with _b_r_l_t_t_y's core, the braille driver and
clients. In this part, a "connection-use-disconnection" scenario
will be described step by step, explaining for each step what
_B_r_l_A_P_I does in reaction to client instructions. These
explanations will take place at a user level.
````CCoonnccuurrrreennccyy mmaannaaggeemmeenntt''''
This part explains how concurrency between _B_r_l_A_P_I clients is
handled thanks to focus tellers.
````IInnssttaallllaattiioonn aanndd ccoonnffiigguurraattiioonn''''
This part explains in detail how to install and configure the
API. For instructions on how to install and configure _b_r_l_t_t_y,
please report to the _b_r_l_t_t_y documentation.
````LLiibbrraarryy ddeessccrriippttiioonn''''
This part describes how client applications can communicate with
the server using the _B_r_l_A_P_I library that comes with _b_r_l_t_t_y. Each
function will be briefly described, classified by categories.
More exhaustive descriptions of every function are available in
the corresponding online manual pages.
````WWrriittiinngg bbrraaiillllee ddrriivveerrss''''
This part describes how the braille drivers included in _b_r_l_t_t_y
should be written in order to take advantage of _B_r_l_A_P_I's
services.
````PPrroottooccooll rreeffeerreennccee''''
This part describes in detail the communication protocol that is
used to communicate between server and clients.
What should be read probably depends on what should be done by
applications with _B_r_l_A_P_I.
Reading chapters ``General description'', ``Concurrency management''
and ``Installation and configuration'' is recommended, since they
provide useful information and (hopefully) lead to a good
understanding of _B_r_l_A_P_I, for an efficient use.
Chapter ``Library description'' concerns writing applications that
take advantage of braille terminals so as to bring specific (and more
useful) information to blind people.
Chapter ``Drivers'' is for braille driver implementation: either
adding a braille driver to _b_r_l_t_t_y or modifying an existing one so that
it can benefit from _B_r_l_A_P_I's features, this chapter will be of
interest, since it describes exactly what is needed to write a driver
for _b_r_l_t_t_y: the core of drivers interface for instance.
Finally, chapter ``Protocol reference'' is for _n_o_t _u_s_i_n_g the library,
but using the _B_r_l_A_P_I server directly, when the library might not be
sufficient: it describes the underlying protocol that will have to be
used to do so.
22.. GGeenneerraall ddeessccrriippttiioonn ooff BBrrllAAPPII
Here is explained what _B_r_l_A_P_I is, and what it precisely does. These
explanations should be simple enough to be accessible to every user.
For a more technical review of _B_r_l_A_P_I's functionalities, please see
chapter ``Libary description''.
22..11.. HHiissttoorriiccaall nnootteess..
Originally, _b_r_l_t_t_y was designed to give access to the Linux console to
visually impaired people, through a braille terminal or a speech
synthetizer. At that time, applications running in the console were
not taking care of the presence of a braille terminal (most
applications didn't even know what a braille terminal was).
This situation where applications are not aware of the presence of a
special device is elegant of course, since it lets use an unlimited
number of applications which don't need to be specially designed for
visually impaired people.
However, it appeared that applications specially designed to take
advantage of a braille terminal could be wanted, to provide the
suitable information to blind users, for instance. The idea of _B_r_l_A_P_I
is to propose an efficient communication mechanism, to control the
braille display, read keys from the braille keyboard, or to exchange
data with the braille terminal at a lower level (e.g. to write file
transfer protocols between braille terminals and Linux systems).
22..22.. WWhhyy BBrrllAAPPII iiss ppaarrtt ooff bbrrllttttyy ..
Instead of rewriting a whole communication program from scratch, we
chose to add communication mechanisms to _b_r_l_t_t_y. This choice has two
main justifications.
On the one hand, integration to _b_r_l_t_t_y allows us to use the increasing
number of drivers written for _b_r_l_t_t_y, thus handling a large number of
braille terminals without having to rewrite any piece of existing
code.
On the other hand, if an application chooses to send its own
information to the braille display, and to process braille keys,
_b_r_l_t_t_y has to be warned, so that it won't try to communicate with the
braille terminal while the application already does. To make this
synchronzation between _b_r_l_t_t_y and client applications possible, it
seemed easier to add the communication mechanisms to _b_r_l_t_t_y's core,
instead of writing an external program providing them.
22..33.. HHooww iitt wwoorrkkss..
We are now going to describe the steps an application should go
through to get control of the braille terminal, and what happens on
_b_r_l_t_t_y's side at each step. This step-by-step description will let us
introduce more precisely some concepts that are useful for every
_B_r_l_A_P_I user.
22..33..11.. CCoonnnneeccttiioonn..
The first thing any client application has to do is to connect (in the
Unix sense of the word) to _B_r_l_A_P_I which is an mere application server.
If this is not clear, the only thing to be remembered is that this
step allows the client application to let the server know about its
presence. At this stage, nothing special is done on _b_r_l_t_t_y's side.
22..33..22.. AAuutthhoorriizzaattiioonn..
Since Unix is designed to allow many users to work on the same
machine, it's quite possible that there are more than one user
accounts on the system. Most probably, one doesn't want any user with
an account on the machine to be able to communicate with the braille
terminal (just imagine what would happen if, while somebody was
working with the braille terminal, another user connected to the
system began to communicate with it, preventing the first one from
doing his job...). That's why _B_r_l_A_P_I has to provide a way to determine
whether a user who established a connection is really allowed to
communicate with the braille terminal. To achieve this, _B_r_l_A_P_I
requires that each application that wants to control a braille
terminal sends an authorization key before doing anything else. The
control of the braille terminal will only be possible for the client
once it has sent the proper authorization key. What is called
authorization key is in fact a Unix file containing data (it must be
non-empty) on your system. All the things you have to do is to give
read permissions on this file to users that are allowed to communicate
with the braille terminal, and only to them. This way, only authorized
users will have access to the authorization key and then be able to
send it to _B_r_l_A_P_I. To see how to do that, please see chapter
``Installation and configuration''.
At the end of this step, the user is authorized to take control of the
braille terminal. On _b_r_l_t_t_y's side, some data structures are allocated
to store information on the client, but this has no user-level side-
effect.
22..33..33.. RReeaall uussee ooff tthhee bbrraaiillllee tteerrmmiinnaall..
Once the client is properly connected and authorized, there are two
possible types of communication with the braille terminal. The chosen
type of communication depends on what the client plans to do. If its
purpose is to display information on the braille display or to process
braille keys, it will have to take control of the Linux tty on which
it is running. If its purpose is to exchange data with the braille
terminal (e.g. for file transfer), it will enter what is called "raw
mode".
22..33..33..11.. BBrraaiillllee ddiissppllaayy aanndd bbrraaiillllee kkeeyy pprreesssseess pprroocceessssiinngg..
If the client wants to display something on the braille display or to
process braille keys itself, rather than letting _b_r_l_t_t_y process them,
it has to take control of the Linux terminal it is running on.
Once a client has obtained the control of his tty, _B_r_l_A_P_I will
completely discard _b_r_l_t_t_y's display on this tty (and only this one),
leaving the braille display free for the client.
At the same time, if a key is pressed on the braille keyboard, _B_r_l_A_P_I
checks whether the client application is interested in this key or
not. If it is, the key is passed to it, either as a key code or as a
_b_r_l_t_t_y command. If it is not, the key code is converted into a _b_r_l_t_t_y
command and returned to _b_r_l_t_t_y.
Once the client is not interested in displaying text or reading
braille keys any more, it has to leave the tty, so that either _b_r_l_t_t_y
can continue its job, or another client can take control of it.
22..33..33..22.. RRaaww mmooddee..
Only one client can be in raw mode at the same time. In this mode,
data coming from the braille terminal are checked by the driver (to
ensure they are valid), but instead of being processed, they are
delivered "as-is" to the client that is in raw mode.
In the other direction, packets sent to _B_r_l_A_P_I by the client that is
in raw mode are passed to the driver which is expected to deliver them
to the braille terminal without any modification.
22..33..33..33.. SSuussppeenndd MMooddee..
Only one client can be in suspend mode at the same time. This mode is
also exclusive with raw mode. In this mode, the server keeps the
device driver closed, and thus the client can open the device directly
by itself.
TThhiiss mmooddee iiss nnoott rreeccoommmmeennddeedd, since the client will then have to
reimplement device access. Raw mode should really be preferred, since
it lets the client take advantage of server's ability to talk with the
device (USB/bluetooth support for instance).
22..33..33..44.. RReemmaarrkkss..
· The operations described in the three previous subsections are not
completely mutually exclusive. An application that controls its
current tty can enter raw or suspend mode, provided that no other
application already is in this mode.
· Not every braille driver supports raw mode. It has to be specially
(re)written to support it, since it has to provide special
functions to process incoming and outgoing packets. The same
restriction is true (but less strong) concerning the ability to
deliver/convert keycodes into commands: not every driver has this
ability, it has to be modified to get it.
· Operations previously described can be repeated. You can, for
instance, use raw mode to transfer data onto your braille terminal,
display text in braille, return to raw mode..., all that without
having to reconnect to _B_r_l_A_P_I before each operation.
22..33..44.. DDiissccoonnnneeccttiioonn..
Once the client has finished using the braille terminal, it has to
disconnect from the API, so that the memory structures allocated for
the connection can be freed and eventually used by another client.
This step is transparent for the user, in the sense that it involves
no change on the braille display.
33.. CCoonnccuurrrreennccyy mmaannaaggeemmeenntt bbeettwweeeenn BBrrllAAPPII cclliieennttss
An essential purpose of _B_r_l_A_P_I is to manage concurrent access to the
braille display between the _b_r_l_t_t_y daemon and applications. This
concurrency is managed "per Tty". We first describe this with a flat
view, and then consider Tty hierarchy.
33..11.. VVTT sswwiittcchhiinngg
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 _B_r_l_A_P_I client has to "get" a tty, i.e. it sends to the
_B_r_l_A_P_I server the number of the linux' Virtual Tty on which it is
running. The _B_r_l_A_P_I 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 _B_r_l_A_P_I connection. The focus teller is _b_r_l_t_t_y here:
it always tells to the _B_r_l_A_P_I 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 _B_r_l_A_P_I server shows _b_r_l_t_t_y's output
on the braille display. I.e. the usual _b_r_l_t_t_y screen reading appears.
Moreover, when braille keys are pressed, they are passed to _b_r_l_t_t_y, so
that usual screen reading can be performed. When the user switches to
VT 2, _b_r_l_t_t_y (as focus teller) tells it to the _B_r_l_A_P_I 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, _B_r_l_A_P_I 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 _b_r_l_t_t_y). If it
isn't, it is passed to _b_r_l_t_t_y (and not to _A).
As a consequence, whenever clients get and release Ttys and the user
switches between Ttys, either the _b_r_l_t_t_y screen reading or the
client's output is automatically shown according to rather natural
rules.
33..22.. AA ppiillee ooff ""ppaappeerr sshheeeettss""
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. _b_r_l_t_t_y 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" _b_r_l_t_t_y's sheet: _A's output "mask" _b_r_l_t_t_y's
screen reading.
_A may yet want to temporarily let _b_r_l_t_t_y'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, _b_r_l_t_t_y'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 _b_r_l_t_t_y.
Let's say some other client _B (probably launched by _A) also gets VT 2
and outputs some text on its _B_r_l_A_P_I connection. This adds a third
sheet, on top of the two previous ones. It means that the _B_r_l_A_P_I
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 determined by the Tty "get"ting order. Some
mecanism will be added in near future for clients to precise "at which
level its sheet should be inserted" so as to avoid race conditions on
the "get"ting order.
33..33.. HHiieerraarrcchhyy
Now, what happens when running some _s_c_r_e_e_n 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 _s_c_r_e_e_n
window is active. This hence forms a _t_r_e_e of Ttys: the "root" being
the vga driver's output, whose sons are VTs, and VT 3 has the _s_c_r_e_e_n
windows as sons. _B_r_l_t_t_y is a focus teller for the root, _s_c_r_e_e_n will
have to be a focus teller for VT 3. _S_c_r_e_e_n should then get VT 3, not
display anything (so that the usual _b_r_l_t_t_y screen reading will be
shown by transparency), and tell the _B_r_l_A_P_I server which _s_c_r_e_e_n window
is active (at startup and at each window switch). This is not
implemented directly in _s_c_r_e_e_n yet, but this may be achieved via a
second _b_r_l_t_t_y daemon running the Screen driver (but it isn't yet able
to get the current window number though) and the _B_r_l_A_P_I driver.
A _B_r_l_A_P_I client _C running in some _s_c_r_e_e_n 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 _s_c_r_e_e_n. The VT number, which actually
represents the "path to screen's output" should be available in the
WINDOWPATH environment variable, also set by _s_c_r_e_e_n. 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 _B_r_l_A_P_I 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 _B_r_l_A_P_I
client library will automatically perform all that.
Whenever the user switches to VT 3, the _B_r_l_A_P_I server remembers the
window that _s_c_r_e_e_n told to be active. If it was window 1, it then
displays _C's output (if any). Else _b_r_l_t_t_y's usual screen reading is
shown. Of course, several clients may be run in window 1 as well, and
the "sheet pile" mecanism applies: _b_r_l_t_t_y's sheet first (at the root
of the Ttys tree), then _s_c_r_e_e_n'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.
33..44.. TThhee XX--wwiinnddooww ccaassee
Let's say some X server is running on VT 7 of a Linux system. Xorg's
_x_i_n_i_t and _x_d_m commands automatically set the X session's WINDOWPATH
environment variable to "7", so that X11 _B_r_l_A_P_I clients started from
the session just need to call _b_r_l_a_p_i___e_n_t_e_r_T_t_y_M_o_d_e_(_x_i_d_) where _x_i_d is
the X-window ID of the window of the client. The _B_r_l_A_P_I library will
automatically prepend the content of WINDOWPATH to it.
For text-based _B_r_l_A_P_I clients running in an xterm (which should just
call brlapi_enterTtyMode(BRLAPI_TTY_DEFAULT) as explained in the
previous section), _B_r_l_A_P_I 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 _b_r_l_a_p_i___e_n_t_e_r_T_t_y_M_o_d_e_W_i_t_h_P_a_t_h_(_N_U_L_L_, _0_) to let the _B_r_l_A_P_I library
only send the content of WINDOWPATH, expressing that screen readers
take the whole tty. The user should notably launch _x_b_r_l_a_p_i, which is a
focus teller for X-window as well as a keyboard simulator (_b_r_l_t_t_y
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 _b_r_l_t_t_y daemon
running the at-spi screen driver and the _B_r_l_A_P_I driver can also be
launched. All three would get the VT of the X session, in that order
(for now): _x_b_r_l_a_p_i first, then _o_r_c_a and _b_r_l_t_t_y at last. When the X
focus is on an AT-SPI terminal, _b_r_l_t_t_y will hence be able to grab the
braille display and key presses. Else _o_r_c_a would get them. And _x_b_r_l_a_p_i
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.
33..55.. DDeettaacchhiinngg
Several programs allow detaching: _s_c_r_e_e_n and _V_N_C for instance. In such
situation, an intermediate _B_r_l_A_P_I 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
_B_r_l_A_P_I server. This intermediate server is yet to be written (but it
is actually relatively close to be).
44.. IInnssttaallllaattiioonn aanndd ccoonnffiigguurraattiioonn ooff BBrrllAAPPII
make install will install libbrlapi.so in /lib, and include files in
/usr/include/brltty. An authorization key will also typically be set
in /etc/brlapi.key (if it is not, just create it and put arbitrary
data in it), but it won't be readable by anybody else than root. It is
up to you to define a group of users who will have the right to read
it and hence be able to connect to the server. For instance, you may
want to do:
______________________________________________________________________
# addgroup brlapi
# chgrp brlapi /etc/brlapi.key
# chmod g+r /etc/brlapi.key
# addgroup user1 brlapi
# addgroup user2 brlapi
...
______________________________________________________________________
55.. LLiibbrraarryy ddeessccrriippttiioonn
Let's now see how one can write dedicated applications. Basic notions
will be seen, along with a very simple client. Greater details are
given as online manual pages.
The historical test program for _B_r_l_A_P_I was something like:
· connect to _B_r_l_A_P_I
· get driver id
· get driver name
· get display size
· try entering raw mode, immediately leave raw mode.
· get tty control
· write something on the display
· wait for a key press
· leave tty control
· disconnect from _B_r_l_A_P_I
It is here rewritten, its working briefly explained.
55..11.. CCoonnnneeccttiinngg ttoo BBrrllAAPPII
Connection to _B_r_l_A_P_I is needed first, thanks to the
brlapi_openConnection call. For this, a brlapi_connectionSettings_t
variable must be filled which will hold the settings the library needs
to connect to the server. Just giving NULL will work for local use.
The other parameter lets you get back the parameters which were
actually used to initialize connection. NULL will also be nice for
now.
______________________________________________________________________
if (brlapi_openConnection(NULL, NULL)<0) {
brlapi_perror("brlapi_openConnection");
exit(1);
}
______________________________________________________________________
The connection might fail, so testing is needed.
55..22.. GGeettttiinngg ddrriivveerr nnaammee
Knowing the type of the braille device might be useful:
______________________________________________________________________
char name[BRLAPI_MAXNAMELENGTH+1];
if (brlapi_getDriverName(name, sizeof(name)) < 0)
brlapi_perror("brlapi_getDriverName");
else
fprintf(stderr, "Driver name: %s\n", name);
______________________________________________________________________
This is particularly useful before entering raw mode to achieve file
transfers for instance, just to check that the device is really the
one expected.
55..33.. GGeettttiinngg ddiissppllaayy ssiizzee
Before writing on the braille display, the size should be always first
checked to be sure everything will hold on it:
______________________________________________________________________
if (brlapi_getDisplaySize(&x, &y) < 0)
brlapi_perror("brlapi_getDisplaySize");
else
fprintf(stderr, "Braille display has %d line%s of %d column%s\n",
y, y>1?"s":"", x, x>1?"s":"");
______________________________________________________________________
55..44.. EEnntteerriinngg rraaww mmooddee,, iimmmmeeddiiaatteellyy lleeaavviinngg rraaww mmooddee..
Entering raw mode is very simple:
______________________________________________________________________
fprintf(stderr, "Trying to enter in raw mode... ");
if (brlapi_enterRawMode(name) < 0)
brlapi_perror("brlapi_enterRawMode");
else {
fprintf(stderr, "Ok, leaving raw mode immediately\n");
brlapi_leaveRawMode();
}
______________________________________________________________________
Not every driver supports raw mode, so testing is needed.
While in raw mode, brlapi_sendRaw and brlapi_recvRaw can be used to
send and get data directly to and from the device. It should be used
with care, improper use might completely thrash the device!
55..55.. GGeettttiinngg ttttyy ccoonnttrrooll
Let's now display something on the device. control of the tty must be
get first:
______________________________________________________________________
fprintf(stderr, "Taking control of the tty... ");
if (brlapi_enterTtyMode(BRLAPI_TTY_DEFAULT, NULL) >= 0)
{
fprintf(stderr, "Ok\n");
______________________________________________________________________
The first parameter tells the server the number of the tty to take
control of. Setting BRLAPI_TTY_DEFAULT lets the library determine it
for us.
The server is asked to send _b_r_l_t_t_y commands, which are device-
independent.
Getting control might fail if, for instance, another application
already took control of this tty, so testing is needed.
From now on, the braille display is detached from the screen.
55..66.. WWrriittiinngg ssoommeetthhiinngg oonn tthhee ddiissppllaayy
The application can now write things on the braille display without
altering the screen display:
______________________________________________________________________
fprintf(stderr, "Writing to braille display... ");
if (brlapi_writeText(0, "Press a braille key to continue...") >= 0)
{
fprintf(stderr, "Ok\n");
______________________________________________________________________
The cursor is also asked _n_o_t to be shown: its position is set to 0.
"Writing to braille display... Ok" is now displayed on the screen, and
"Press a braille key to continue..." on the braille display.
55..77.. WWaaiittiinngg ffoorr aa kkeeyy pprreessss
To have a break for the user to be able to read these messages, a key
press (a command here, which is driver-independent) may be waited for:
______________________________________________________________________
fprintf(stderr, "Waiting until a braille key is pressed to continue... ");
if (brlapi_readKey(1, &key) > 0)
fprintf(stderr, "got it! (code=%"BRLAPI_PRIxKEYCODE")\n", key);
______________________________________________________________________
The command is returned, as described in <brlapi_constants.h> and
<brlapi_keycodes.h>. It is not transmitted to _b_r_l_t_t_y: it is up to the
application to define the behavior, here cleanly exitting, as
described below.
The first parameter tells the lib to block until a key press is indeed
read.
55..88.. UUnnddeerrssttaannddiinngg ccoommmmaannddss
There are two kinds of commands: braille commands (line up/down,
top/bottom, etc.) and X Keysyms (i.e. regular keyboard keys). One way
to discover which key was pressed is to just use a switch statement:
______________________________________________________________________
switch(key) {
case BRLAPI_KEY_TYPE_CMD|BRLAPI_KEY_CMD_LNUP:
fprintf(stderr, "line up\n");
break;
case BRLAPI_KEY_TYPE_CMD|BRLAPI_KEY_CMD_LNDN:
fprintf(stderr, "line down\n");
break;
case BRLAPI_KEY_TYPE_SYM|XK_Tab:
fprintf(stderr, "tab\n");
break;
default:
fprintf(stderr, "unknown key\n");
break;
}
______________________________________________________________________
Another way is to ask BrlAPI to expand the keycode into separate
information parts:
______________________________________________________________________
brlapi_expandedKeyCode_t ekey;
brlapi_expandKeyCode(key, &ekey);
fprintf(stderr, "type %u, command %u, argument %u, flags %u\n",
ekey.type, ekey.command, ekey.argument, ekey.flags);
______________________________________________________________________
Eventually, named equivalents are provided:
______________________________________________________________________
brlapi_describedKeyCode_t dkey;
int i;
brlapi_describeKeyCode(key, &dkey);
fprintf(stderr, "type %s, command %s, argument %u, flags",
dkey.type, dkey.command, dkey.argument);
for (i = 0; i < dkey.flags; i++)
fprintf(stderr, " %s", dkey.flag[i]);
fprintf(stderr, "\n");
______________________________________________________________________
55..99.. LLeeaavviinngg ttttyy ccoonnttrrooll
Let's now leave the tty:
______________________________________________________________________
fprintf(stderr, "Leaving tty... ");
if (brlapi_leaveTtyMode() >= 0)
fprintf(stderr, "Ok\n");
______________________________________________________________________
But control of another tty can still be get for instance, by calling
brlapi_enterTtyMode() again...
55..1100.. DDiissccoonnnneeccttiinngg ffrroomm BBrrllAAPPII
Let's disconnect from _B_r_l_A_P_I:
______________________________________________________________________
brlapi_closeConnection();
______________________________________________________________________
The application can as well still need to connect to another server on
another computer for instance, by calling brlapi_openConnection()
again...
55..1111.. PPuuttttiinngg eevveerryytthhiinngg ttooggeetthheerr......
______________________________________________________________________
#include <stdio.h>
#include <stdlib.h>
#include <brlapi.h>
int main()
{
brlapi_keyCode_t key;
char name[BRLAPI_MAXNAMELENGTH+1];
unsigned int x, y;
/* Connect to BrlAPI */
if (brlapi_openConnection(NULL, NULL)<0)
{
brlapi_perror("brlapi_openConnection");
exit(1);
}
/* Get driver name */
if (brlapi_getDriverName(name, sizeof(name)) < 0)
brlapi_perror("brlapi_getDriverName");
else
fprintf(stderr, "Driver name: %s\n", name);
/* Get display size */
if (brlapi_getDisplaySize(&x, &y) < 0)
brlapi_perror("brlapi_getDisplaySize");
else
fprintf(stderr, "Braille display has %d line%s of %d column%s\n",
y, y>1?"s":"", x, x>1?"s":"");
/* Try entering raw mode, immediately go out from raw mode */
fprintf(stderr, "Trying to enter in raw mode... ");
if (brlapi_enterRawMode(name) < 0)
brlapi_perror("brlapi_enterRawMode");
else {
fprintf(stderr, "Ok, leaving raw mode immediately\n");
brlapi_leaveRawMode();
}
/* Get tty control */
fprintf(stderr, "Taking control of the tty... ");
if (brlapi_enterTtyMode(BRLAPI_TTY_DEFAULT, NULL) >= 0)
{
fprintf(stderr, "Ok\n");
/* Write something on the display */
fprintf(stderr, "Writing to braille display... ");
if (brlapi_writeText(0, "Press a braille key to continue...") >= 0)
{
fprintf(stderr, "Ok\n");
/* Wait for a key press */
fprintf(stderr, "Waiting until a braille key is pressed to continue... ");
if (brlapi_readKey(1, &key) > 0) {
brlapi_expandedKeyCode_t ekey;
brlapi_describedKeyCode_t dkey;
int i;
fprintf(stderr, "got it! (code=%"BRLAPI_PRIxKEYCODE")\n", key);
brlapi_expandKeyCode(key, &ekey);
fprintf(stderr, "type %u, command %u, argument %u, flags %u\n",
ekey.type, ekey.command, ekey.argument, ekey.flags);
brlapi_describeKeyCode(key, &dkey);
fprintf(stderr, "type %s, command %s, argument %u, flags",
dkey.type, dkey.command, dkey.argument);
for (i = 0; i < dkey.flags; i++)
fprintf(stderr, " %s", dkey.flag[i]);
fprintf(stderr, "\n");
} else brlapi_perror("brlapi_readKey");
} else brlapi_perror("brlapi_writeText");
/* Leave tty control */
fprintf(stderr, "Leaving tty... ");
if (brlapi_leaveTtyMode() >= 0)
fprintf(stderr, "Ok\n");
else brlapi_perror("brlapi_leaveTtyMode");
} else brlapi_perror("brlapi_enterTtyMode");
/* Disconnect from BrlAPI */
brlapi_closeConnection();
return 0;
}
______________________________________________________________________
This should compile well thanks to gcc apiclient.c -o apiclient
-lbrlapi
66.. WWrriittiinngg (( BBrrllAAPPII --ccoommpplliiaanntt)) ddrriivveerrss ffoorr bbrrllttttyy
In this chapter, we will describe in details how to write a driver for
_b_r_l_t_t_y. We begin with a general description of the structure the
driver should have, before explaining more precisely what each
function is supposed to do.
66..11.. OOvveerrvviieeww ooff tthhee ddrriivveerr''ss ssttrruuccttuurree
A braille driver is in fact a library that is either dynamically
loaded by _b_r_l_t_t_y at startup, or statically linked to it during the
compilation, depending on the options given to the ./configure script.
This library has to provide every function needed by the core, plus
some additional functions, that are not mandatory, but which improve
communication with _B_r_l_A_P_I and the service level provided to client
applications.
Basically, a driver library needs to provide a function to open the
communication with the braille terminal, one to close this
communication, one to read key codes from the braille keyboard, and
one to write text on the braille display. As we will see in a moment,
other functions are required.
Moreover, a driver can provide additional functionalities, by defining
some macros asserting that it has these functionalities, and by
defining associated functions.
66..22.. BBaassiicc ddrriivveerr ssttrruuccttuurree
_E_v_e_r_y _b_r_l_t_t_y driver _m_u_s_t consist in at least a file called braille.c,
located in an appropriate subdirectory of the BrailleDrivers
subdirectory. This braille.c file must have the following layout
#include "prologue.h"
/* Include standard C headers */
#include "Programs/brl.h"
#include "Programs/misc.h"
#include "Programs/scr.h"
#include "Programs/message.h"
/* Include other files */
static void brl_identify() { }
static int brl_open(BrailleDisplay *brl, char **parameters, const char *tty) { ... }
static void brl_close(BrailleDisplay *brl) { ... }
static void brl_writeWindow(BrailleDisplay *brl) { ... }
static void brl_writeStatus(BrailleDisplay *brl) { ... }
static int brl_readCommand(BrailleDisplay *brl, DriverCommandContext context) { ... }
Before giving a detailed description of what each function is supposed
to do, we define the BrailleDisplay structure, since each function has
an argument of type BrailleDisplay *. The BrailleDisplay structure is
defined like this:
typedef struct {
int x, y; /* The dimensions of the display */
int helpPage; /* The page number within the help file */
unsigned char *buffer; /* The contents of the display */
unsigned isCoreBuffer:1; /* The core allocated the buffer */
unsigned resizeRequired:1; /* The display size has changed */
unsigned int writeDelay;
void (*bufferResized)(int rows, int columns);
} BrailleDisplay;
We now describe each function's semantics and calling convention.
The brl_identify() function takes no argument and returns nothing. It
is called as soon as the driver is loaded, and its purpose is to print
some information about the driver in the system log. To achieve this,
the only thing this function has to do is to call LOG_PRINT with
appropriate arguments (log level and string to put in the syslog).
The brl_open() function takes 3 arguments and returns an int. Its
purpose is to initialize the communication with the braille terminal.
Generally, this function has to open the file referred to by the tty
argument, and to configure the associated communication port. The
parameters argument contains parameters passed to the driver with the
-B command-line option. It's up to the driver's author to decide
wether or not he/she wants to use this argument, and what for. The
function can perform some additional tasks such as trying to identify
precisely which braille terminal model is connected to the computer,
by sending it a request and analyzing its answer. The value that is
finally returned depends on the success of the initialization process.
If it fails, th function has to return -1. The function returns 0 on
success.
The brl_close() function takes just one argument, and returns nothing.
The name of this function should be self-explanatory; it's goal is to
close (finish) the communication between the computer and the braille
terminal. In general, the only thing this function has to do is to
close the file descriptor associated to the braille terminal's
communication port.
The brl_writeWindow() function takes just one argument of type
BrailleDisplay, and returns nothing. This function displays the
specified text on the braille window. This routine is the right place
to check if the text that has to be displayed is not already on the
braille display, to send it only if necessary. More generally, if the
braille terminal supports partial refresh of the display, the calculus
of what exactly has to be sent to the braille display to have a proper
display, according to what was previously displayed should be done in
this function.
The brl_writeStatus() function is very similar to brl_writeWindow().
The only difference is that whereas brl_writeWindow() writes on the
main braille display, brl_writeStatus() writes on an auxiliary braille
display, which occasionaly appears on some braille terminals. The
remarks that have been done concerning optimizations for refreshing
the display still apply here.
The brl_readCommand() function takes two arguments, and returns an
integer. Its purpose is to read commands from the braille keyboard and
to pass them to _b_r_l_t_t_y's core, which in turn will process them. The
first argument, of type BrailleDisplay, is for future use, and can
safely be ignored for the moment. The second argument indicates in
which context (state) _b_r_l_t_t_y is. For instance, it specifies if _b_r_l_t_t_y
is in a menu, displays a help screen, etc. This information can indeed
be of some interest when translating a key into a command, especially
if the keys can have different meanings, depending on the context. So,
this function has to read keypresses from the braille keyboard, and to
convert them into commands, according to the given context, these
commands then being returned to _b_r_l_t_t_y. For a complete list of
available command codes, please have a look at brl.h in the Programs
subdirectory. Two codes have special meanings:
eeooff
specifies that no command is available now, and that no key is
waiting to be converted into command in a near future.
CCMMDD__NNOOOOPP
specifies that no command is available, but that one will be,
soon. As a consequence, brl_readCommand will be called again
immediately. Returning CMD_NOOP is appropriate for instance when
a key is composed of two consecutive data packets. When the
first of them is received, one can expect that the second will
arrive quickly, so that trying to read it as soon as possible is
a good idea.
66..33.. EEnnhhaanncceemmeennttss ffoorr BBrrllAAPPII
To improve the level of service provided to client applications
communicating with braille drivers through _B_r_l_A_P_I, the drivers should
declare some additional functions that will then be called by the API
when needed.
For each additional feature that has to be implemented in a driver, a
specific macro must be defined, in addition to the functions
implementing that feature. For the moment, two features are supported
by _B_r_l_A_P_I:
· reading braille terminal specific key codes,
· exchanging raw data packets between the braille terminal and a
client application running on the PC.
For each feature presented below, only a short description of each
concerned macro and function will be given. For a more complete
description of concepts used here, please refer to chapters
``Introduction'' and ``General description''.
66..33..11.. RReeaaddiinngg bbrraaiillllee kkeeyy ccooddeess
When a client takes control of a tty and asks for getting raw key
codes, it has, like in command mode, the possibility to mask some
keys. The masked keys will then be passed to _b_r_l_t_t_y. This assumes the
existence of a conversion mechanism from key codes to _b_r_l_t_t_y commands.
This conversion mechanism can only be implemented by the braille
driver, since it is the only piece of code that knows about braille
terminal specific key codes. So, to make it possible for client
applications to read raw key codes, the driver has to define the
following macro:
#define BRL_HAVE_KEY_CODES
and the following functions:
static int brl_readKey(BrailleDisplay *)
int brl_keyToCommand(BrailleDisplay *brl, DriverCommandContext caller, int code)
The semantics of brl_readKey() is very similar to brl_readCommand()'s,
with one essential difference: a key code is not context-dependant, so
no context argument needs to be given to this function. Moreover, the
code this function returns is driver-specific, and has to be properly
defined by the driver's author so that client applications can rely on
it.
The brl_keyToCommand() function's purpose is to convert a key code as
delivered by brl_readKey() into a _b_r_l_t_t_y command. As explained above,
this function is called by brlapi when a key is pressed on the braille
keyboard that is ignored by the client application. The corresponding
command is then returned to _b_r_l_t_t_y.
66..33..11..11.. RReemmaarrkkss
When these two functions are present, the only thing brl_readCommand()
has to do is to call brl_readKey() and then call brl_keyToCommand()
with the value returned by the first function as argument.
66..33..22.. EExxcchhaannggiinngg rraaww ddaattaa ppaacckkeettss
Under some circumstances, an application running on the PC can be
interested in a raw level communication with the braille terminal. For
instance, to implement a file transfer protocol, commands to display
braille or to read keys are not enough. In such a case, one must have
a way to send raw data to the terminal, and to receive them from it.
A driver that wants to provide such a mechanism has to define three
functions: one to send packets, another one to receive them, and the
last one to reset the communication when problems occur.
The macro that declares that a driver is able to transmit packets is:
#define BRL_HAVE_PACKET_IO
The prototypes of the functions the driver should define are:
static int brl_writePacket(BrailleDisplay *brl, const unsigned char *packet, int size);
static int brl_readPacket(BrailleDisplay *brl, unsigned char *p, int size);
static void brl_rescue(BrailleDisplay *brl)
brl_writePacket() sends a packet of size bytes, stored at packet, to
the braille terminal. If the communication protocol allows to
determined if a packet has been send properly (e.g. the terminal sends
back an acknowledgement for each packet he receives), then this
function should wait the acknowledgement, and, if it is not received,
retransmission of the packet should take place.
brl_readPacket() reads a packet of at most size bytes, and stores it
at the specified address. The read must not block. I.e., if no packet
is available, the function should return immediately, returning 0.
brl_rescue() is called by _B_r_l_A_P_I when a client application terminates
without properly leaving the raw mode. This function should restore
the terminal's state, so that it is able to display text in braille
again.
66..33..22..11.. RReemmaarrkkss..
· If the driver provides such functions, every other functions should
use them, instead of trying to communicate directly with the
braille terminal. For instance, readCommand() should call
readPacket(), and then extract a key from the packet, rather than
reading directly from the communication port's file descriptor. The
same applies for brl_writeWindow(), which should use
brl_writePacket(), rather than writing on the communication port's
file descriptor.
· For the moment, the argument of type BrailleDisplay can safely be
ignored by the functions described here.
77.. PPrroottooccooll rreeffeerreennccee
Under some circumstances, it may be preferable to communicate directly
with _B_r_l_A_P_I's server rather than using _B_r_l_A_P_I's library. Here are the
needed details to be able to do this. This chapter is also of interest
if a precise understanding of how the communication stuff works is
desired, to be sure to understand how to write multithreaded clients,
for instance.
In all the following, _i_n_t_e_g_e_r will mean an unsigned 32 bits integer in
network byte order (ie most significant bytes first).
77..11.. RReelliiaabbllee ppaacckkeett ttrraannssmmiissssiioonn cchhaannnneell
The protocol between _B_r_l_A_P_I's server and clients is based on exchanges
of packets. So as to avoid locks due to packet loss, these exchanges
are supposed reliable, and ordering must be preserved, thus _B_r_l_A_P_I
needs a reliable packet transmission channel.
To achieve this, _B_r_l_A_P_I uses a TCP-based connection, on which packets
are transmitted this way:
· the size in bytes of the packet is transmitted first as an integer,
· then the type of the packet, as an integer,
· and finally the packet data.
The size does not include the { size, type } header, so that packets
which don't need any data have a size of 0 byte. The type of the
packet can be either of BRLAPI_PACKET_* constants defined in
api_protocol.h. Each type of packet will be further discussed below.
_B_r_l_A_P_I's library ships two functions to achieve packets sending and
receiving using this protocol: brlapi_writePacket and
brlapi_readPacket. It is a good idea to use these functions rather
than rewriting them, since this protocol might change one day in favor
of a real reliable packet transmission protocol such as the
experimental RDP.
77..22.. RReessppoonnsseess ffrroomm tthhee sseerrvveerr
As described below, many packets are `acknowledged'. It means that
upon reception, the server sends either:
· a BRLAPI_PACKET_ACK packet, with no data, which means the operation
corresponding to the received packet was successful,
· or a BRLAPI_PACKET_ERROR packet, the data being an integer which
should be one of BRLAPI_ERROR_* constants. This means the operation
corresponding to the received packet failed.
Some other packets need some information as a response. Upon
reception, the server will send either:
· a packet of the same type, its data being the response,
· or a BRLAPI_PACKET_ERROR packet.
If at some point an ill-formed or non-sense packet is received by the
server, and BRLAPI_PACKET_EXCEPTION is returned, holding the guilty
packet for further analysis.
77..33.. OOppeerraattiinngg mmooddeess
The connection between the client and the server can be in either of
the four following modes:
· authorization mode: this is the initial mode, when the client
hasn't got the authorization to use the server yet. The server
first sends a BRLAPI_PACKET_VERSION packet that announces the
server version. The client must send back a BRLAPI_PACKET_VERSION
for announcing its own version too. The server then sends a
BRLAPI_PACKET_AUTH packet that announces which authorization
methods are allowed. The client can then send BRLAPI_PACKET_AUTH
packets, which makes the connection enter normal mode. If no
authorization is needed, the server can announce the NONE method,
the client then doesn't need to send a BRLAPI_PACKET_AUTH packet.
· normal mode: the client is authorized to use the server, but didn't
ask for a tty or raw mode. The client can send either of these
types of packet:
· BRLAPI_PACKET_GETDRIVERID, BRLAPI_PACKET_GETDRIVERNAME or
BRLAPI_PACKET_GETDISPLAYSIZE to get pieces of information from
the server,
· BRLAPI_PACKET_ENTERTTYMODE to enter tty handling mode,
· BRLAPI_PACKET_ENTERRAWMODE to enter raw mode,
· tty handling mode: the client holds the control of a tty: _b_r_l_t_t_y
has no power on it any more, masked keys excepted. It's up to the
client to manage display and keypresses. For this, it can send
either of these types of packet:
· BRLAPI_PACKET_ENTERTYMODE to switch to another tty, but how key
presses should be sent mustn't change,
· BRLAPI_PACKET_LEAVETTYMODE to leave tty handling mode and go
back to normal mode,
· BRLAPI_PACKET_IGNOREKEYRANGE and BRLAPI_PACKET_ACCEPTKEYRANGE to
mask and unmask keys,
· BRLAPI_PACKET_WRITE to display text on this tty,
· BRLAPI_PACKET_ENTERRAWMODE to enter raw mode,
· BRLAPI_PACKET_GETDRIVERID, BRLAPI_PACKET_GETDRIVERNAME or
BRLAPI_PACKET_GETDISPLAYSIZE to get pieces of information from
the server,
And the server might send BRLAPI_PACKET_KEY packets to signal key
presses.
· raw mode: the client wants to exchange packets directly with the
braille terminal. Only these types of packet will be accepted.
· BRLAPI_PACKET_LEAVERAWMODE to get back to previous mode, either
normal or tty handling mode.
· BRLAPI_PACKET_PACKET to send a packet to the braille terminal.
And the server might send BRLAPI_PACKET_PACKET packets to give
received packets from the terminal to the client.
· suspend mode: the client wants to completely drive the braille
terminal. The device driver is hence kept closed. No type of
packet is allowed except BRLAPI_PACKET_RESUME
Termination of the connection is initiated by the client in normal
mode by simply closing its side of the socket. The server will then
close the connection.
77..44.. DDeettaaiillss ffoorr eeaacchh ttyyppee ooff ppaacckkeett
Here is described the semantics of each type of packet. Most of them
are directly linked to some of _B_r_l_A_P_I's library's functions. Reading
their online manual page as well will hence be of good help for
understanding.
77..44..11.. BBRRLLAAPPII__PPAACCKKEETT__VVEERRSSIIOONN TThhiiss mmuusstt bbee tthhee ffiirrsstt ppaacckkeett eevveerr
ttrraannssmmiitttteedd ffrroomm tthhee sseerrvveerr ttoo tthhee cclliieenntt aanndd ffrroomm tthhee cclliieenntt ttoo tthhee
sseerrvveerr.. TThhee sseerrvveerr sseennddss oonnee ffiirrsstt ffoorr lleettttiinngg tthhee cclliieenntt kknnooww iittss
pprroottooccooll vveerrssiioonn.. DDaattaa iiss aann iinntteeggeerr iinnddiiccaattiinngg tthhee pprroottooccooll vveerrssiioonn..
TThheenn cclliieenntt mmuusstt tthheenn rreessppoonndd tthhee ssaammee wwaayy ffoorr ggiivviinngg iittss vveerrssiioonn.. IIff
tthhee pprroottooccooll vveerrssiioonn ccaann''tt bbee hhaannddlleedd bbyy tthhee sseerrvveerr,, aa
BBRRLLAAPPII__EERRRROORR__PPRROOTTOOCCOOLL__VVEERRSSIIOONN eerrrroorr ppaacckkeett iiss rreettuurrnneedd aanndd tthhee ccoonnnneecc--
ttiioonn iiss cclloosseedd..
77..44..22.. BBRRLLAAPPII__PPAACCKKEETT__AAUUTTHH
This must be the second packet ever transmitted from the server to the
client and from the client to the server. The server sends one first
for letting the client know which authorization methods are available.
Data is the allowed authorization types, as integers.
If the NONE method is not announced by the server, the client can then
try to get authorized by sending packets whose data is the type of
authorization that is tried (as an integer), and eventually some data
(if the authorization type needs it).
If the authorization is successful, the server acknowledges the
packet, and other types of packets might be used, other
BRLAPI_PACKET_AUTH shouldn't be sent by the client.
If the authorization is not successful, the server sends a
BRLAPI_ERROR_AUTHENTICATION error, and the client can try another
authorization method.
Authorization methods are as follow:
· NONE: the client doesn't need to send an authorization packet.
· KEY: data holds a secret key, the authorization is successful only
if the key matches the server secret key.
· CREDENTIALS: Operating-System-specific credentials are explicitely
sent over the socket, the authorization is successful if the server
considers the credentials sufficient.
Note: when the Operating system permits it, the server may use
implicit credential check, and then advertise the none method.
77..44..33.. BBRRLLAAPPII__PPAACCKKEETT__GGEETTDDRRIIVVEERRIIDD ((sseeee bbrrllaappii__ggeettDDrriivveerrIIdd(()) ))
This should be sent by the client when it needs the 2-char identifier
of the current brltty driver. The returned string is \0 terminated.
77..44..44.. BBRRLLAAPPII__PPAACCKKEETT__GGEETTDDRRIIVVEERRNNAAMMEE ((sseeee bbrrllaappii__ggeettDDrriivveerrNNaammee(()) ))
This should be sent by the client when it needs the full name of the
current brltty driver. The returned string is \0 terminated.
77..44..55.. BBRRLLAAPPII__PPAACCKKEETT__GGEETTDDIISSPPLLAAYYSSIIZZEE ((sseeee bbrrllaappii__ggeettDDiissppllaayySSiizzee(()) ))
This should be sent by the client when it needs to know the braille
display size. The returned data are two integers: width and then
height.
77..44..66.. BBRRLLAAPPII__PPAACCKKEETT__EENNTTEERRTTTTYYMMOODDEE ((sseeee bbrrllaappii__eenntteerrTTttyyMMooddee(()) aanndd
bbrrllaappii__eenntteerrTTttyyMMooddeeWWiitthhPPaatthh(()) ))
This should be sent by the client to get control of a tty. Sent data
are first a series of integers: the first one gives the number of
following integers, which are the numbers of ttys that leads to the
tty that the application wants to take control of (it can be empty if
the tty is one of the machine's VT). The last integer of this series
tells the number of the tty to get control of. Finaly, how key presses
should be reported is sent: either a driver name or "", preceded by
the number of caracters in the driver name (0 in the case of ""), as
an unsigned byte. This packet is then acknowledged by the server.
77..44..77.. BBRRLLAAPPII__PPAACCKKEETT__KKEEYY ((sseeee bbrrllaappii__rreeaaddKKeeyy(()) ))
As soon as the client gets a tty, it must be prepared to handle
BRLAPI_PACKET_KEY incoming packets at any time (as soon as the key was
pressed on the braille terminal, hopefuly). The data holds a key code
as 2 integers, or the key flags then the command code as 2 integers,
depending on what has been request in the BRLAPI_PACKET_ENTERTTYMODE
packet.
77..44..88.. BBRRLLAAPPII__PPAACCKKEETT__SSEETTFFOOCCUUSS ((sseeee bbrrllaappii__sseettFFooccuuss(()) ))
For the server to know which tty is active, one particular client is
responsible for sending BRLAPI_PACKET_SETFOCUS packets. They hold a
single integer telling the new current tty. For instance, when running
an X server on VT 7, the xbrlapi client would have sent a
BRLAPI_PACKET_ENTERTTYMODE(7) and will send window IDs whenever X
focus changes, allowing display and keypresses switching between
xterms.
77..44..99.. BBRRLLAAPPII__PPAACCKKEETT__LLEEAAVVEETTTTYYMMOODDEE ((sseeee bbrrllaappii__lleeaavveeTTttyyMMooddee(()) ))
This should be sent to free the tty and masked keys lists. This is
acknowledged by the server.
77..44..1100.. BBRRLLAAPPII__PPAACCKKEETT__IIGGNNOORREEKKEEYYRRAANNGGEE aanndd BBRRLLAAPPII__PPAACCKKEETT__AACCCCEEPPTTKKEEYYRRAANNGGEE
((sseeee bbrrllaappii__iiggnnoorreeKKeeyyRRaannggee(()) aanndd bbrrllaappii__aacccceeppttKKeeyyRRaannggee(()) ))
If the client doesn't want every key press to be signaled to it, but
some of them to be given to brltty for normal processing, it can send
BRLAPI_PACKET_IGNOREKEYRANGE packets to tell ranges of key codes which
shouldn't be sent to it, but given to brltty, and
BRLAPI_PACKET_ACCEPTKEYRANGE packets to tell ranges of key codes which
should be sent to it, and not given to brltty. The server keeps a
dynamic list of ranges, so that arbitrary sequences of such packets
can be sent. For ranges, Data are 2 pairs of integers: the lower and
the upper boundaries; lower and upper must be equal to tell one key,
for instance. For Sets, Data simply consists of pairs of integers,
one per key in the set.
77..44..1111.. BBRRLLAAPPII__PPAACCKKEETT__WWRRIITTEE ((sseeee bbrrllaappii__wwrriittee(()) ))
To display text on the braille terminal and set the position of the
cursor, the client can send a BRLAPI_PACKET_WRITE packet. The packet
begins with an integer holding flags (see BRLAPI_WF_*). These flags
indicate which data will then be available, in the following order
(corresponding to flag weight):
· A display number can be given as a integer, in case the braille
display has several. If not given, usual display is used.
· A region must be given as two integers indicating the beginning and
the number of characters of the part of the braille display which
is to be updated, the first cell of the display being numbered 1.
· The text to display can then be given, preceded by its size in
bytes expressed as an integer. It will erase the corresponding
region in the AND and OR fields. The text's length in characters
must exactly match the region size. For multibyte text, this is the
number of wide characters. Notably, combining and double-width
characters count for 1.
· Then an AND field can be given, one byte per character: the 8-dot
representation of the above text will be AND-ed with this field,
hence allowing to erase some unwanted parts of characters. Dots are
coded as described in ISO/TR 11548-1: dot 1 is set iff bit 0 is
set, dot 2 is set iff bit 1 is set, ... dot _i_+_1 is set if bit _i is
set. This also corresponds to the low-order byte of the coding of
unicode's braille row U+2800.
· As well, an OR field may be given, one byte per character: the
8-dot result of the AND operation above (or the 8-dot
representation of the text if no AND operation was performed) is
OR-ed with this field, hence allowing to set some dots, to
underline characters for instance.
· A cursor position can be specified. 1 representing the first
character of the display, 0 turning the cursor off. If not given,
the cursor (if any) is left unmodified.
· Last but not least, the charset of the text can be specified: the
length of the name first in one byte, then the name itself in ASCII
characters. If the charset is not specified, an 8-bit charset is
assumed, and it is assumed to be the same as the server's.
Multibyte charsets may be used, AND and OR fields' bytes will
correspond to each text's wide _c_h_a_r_a_c_t_e_r, be it a combining or a
double-width character.
A BRLAPI_PACKET_WRITE packet without any flag (and hence no data)
means a "void" WRITE: the server clears the output buffer for this
connection.
77..44..1122.. BBRRLLAAPPII__PPAACCKKEETT__EENNTTEERRRRAAWWMMOODDEE ((sseeee bbrrllaappii__eenntteerrRRaawwMMooddee(()) ))
To enter raw mode, the client must send a BRLAPI_PACKET_ENTERRAWMODE
packet, which is acknowledged. Once in raw mode, no other packet than
BRLAPI_PACKET_LEAVERAWMODE or BRLAPI_PACKET_PACKET will be accepted.
The data must hold the special value BRLAPI_DEVICE_MAGIC: 0xdeadbeef,
then the name of the driver (one byte for the length, then the name)
to avoid erroneous raw mode activating.
77..44..1133.. BBRRLLAAPPII__PPAACCKKEETT__LLEEAAVVEERRAAWWMMOODDEE ((sseeee bbrrllaappii__lleeaavveeRRaawwMMooddee(()) ))
To leave raw mode, the client must send a BRLAPI_PACKET_LEAVERAWMODE
packet, which is acknowledged.
77..44..1144.. BBRRLLAAPPII__PPAACCKKEETT__PPAACCKKEETT ((sseeee bbrrllaappii__sseennddRRaaww(()) aanndd
bbrrllaappii__rreeccvvRRaaww(()) ))
While in raw mode, only BRLAPI_PACKET_PACKET packets can be exchanged
between the client and the server: to send a packet to the braille
terminal, the client merely sends a BRLAPI_PACKET_PACKET packet, its
data being the packet to send to the terminal. Whenever its receives a
packet from the terminal, the server does exactly the same, so that
packet exchanges between the terminal and the server are exactly
reproduced between the server and the client.
77..44..1155.. BBRRLLAAPPII__PPAACCKKEETT__SSUUSSPPEENNDDDDRRIIVVEERR ((sseeee bbrrllaappii__ssuussppeennddDDrriivveerr(()) ))
To enter suspend mode, the client must send a BRLAPI_PACKET_SUSPEND
packet, which is acknowledge. Once in suspend mode, no other packet
than BRLAPI_PACKET_RESUME will be accepted. The data must hold the
special value BRLAPI_DEVICE_MAGIC: 0xdeadbeef, then the name of the
driver (one byte for the length, then the name) to avoid erroneous raw
mode activating.
