Software: Apache/2.2.3 (CentOS). PHP/5.1.6 

uname -a: Linux mx-ll-110-164-51-230.static.3bb.co.th 2.6.18-194.el5PAE #1 SMP Fri Apr 2 15:37:44
EDT 2010 i686 

uid=48(apache) gid=48(apache) groups=48(apache) 

Safe-mode: OFF (not secure)

/usr/share/doc/brlapi-0.4.1/BrlAPI-HTML/   drwxr-xr-x
Free 50.94 GB of 127.8 GB (39.86%)
                            Encoder    Tools    Proc.    FTP brute    Sec.    SQL    PHP-code    Update    Feedback    Self remove    Logout    

Viewing file:     BrlAPI-2.html (9.07 KB)      -rw-r--r--

2. General description of BrlAPI

Here is explained what BrlAPI is, and what it precisely does. These explanations should be simple enough to be accessible to every user. For a more technical review of BrlAPI's functionalities, please see chapter Libary description.

2.1 Historical notes.

Originally, brltty 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 BrlAPI 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).

2.2 Why BrlAPI is part of brltty.

Instead of rewriting a whole communication program from scratch, we chose to add communication mechanisms to brltty. This choice has two main justifications.

On the one hand, integration to brltty allows us to use the increasing number of drivers written for brltty, 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, brltty 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 brltty and client applications possible, it seemed easier to add the communication mechanisms to brltty's core, instead of writing an external program providing them.

2.3 How it works.

We are now going to describe the steps an application should go through to get control of the braille terminal, and what happens on brltty's side at each step. This step-by-step description will let us introduce more precisely some concepts that are useful for every BrlAPI user.

Connection.

The first thing any client application has to do is to connect (in the Unix sense of the word) to BrlAPI 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 brltty's side.

Authentication.

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 BrlAPI 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, BrlAPI requires that each application that wants to control a braille terminal sends an authentication key before doing anything else. The control of the braille terminal will only be possible for the client once it has sent the proper authentication key. What is called authentication 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 authentication key and then be able to send it to BrlAPI. 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 brltty's side, some data structures are allocated to store information on the client, but this has no user-level side-effect.

Real use of the braille terminal.

Once the client is properly connected and authenticated, 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".

Braille display and braille key presses processing.

If the client wants to display something on the braille display or to process braille keys itself, rather than letting brltty 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, BrlAPI will completely discard brltty'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, BrlAPI 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 brltty command. If it is not, the key code is converted into a brltty command and returned to brltty.

Once the client is not interested in displaying text or reading braille keys any more, it has to leave the tty, so that either brltty can continue its job, or another client can take control of it.

Raw mode.

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 BrlAPI 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.

Remarks.

• The operations described in the two previous subsections are not completely mutually exclusive. An application that controls its current tty can enter raw mode, provided that no other application already is in this mode. However, the contrary is not possible: an application which has entered raw mode cannot take control of its tty before having left raw mode. Indeed, it would make no sense to take control of a tty during raw mode since in this mode, braille display and reading of braille keys are impossible.
• 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 BrlAPI before each operation.

Disconnection.

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.