BrlAPI Reference manual: Library description

Next Previous Contents

## 4. Library description

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 BrlAPI was something like:

- connect to BrlAPI
- 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 BrlAPI

It is here rewritten, its working briefly explained.

## 4.1 Connecting to BrlAPI

Connection to BrlAPI is needed first, thanks to the `brlapi_initializeConnection` call. For this, a `brlapi_settings_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_initializeConnection(NULL,NULL)<0)
>      {
>       brlapi_perror("brlapi_initializeConnection");
>       exit(1);
>      }

> `

The connection might fail, so testing is needed.

## 4.2 Getting driver id and name

Knowing the type of the braille device might be useful (`p` is defined as `char *`):

> `

>      p = brlapi_getDriverId();
>      if (!p)
>       brlapi_perror("brlapi_getDriverId");
>      else
>       printf("Driver id: %s\n",p);

>      p = brlapi_getDriverName();
>      if (!p)
>       brlapi_perror("brlapi_getDriverName");
>      else
>       printf("Driver name: %s\n",p);

> `

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.

## 4.3 Getting display size

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
>       printf("Braille display has %d line%s of %d column%s\n",y,y>1?"s":"",x,x>1?"s":"");

> `

## 4.4 Entering raw mode, immediately leaving raw mode.

Entering raw mode is very simple:

> `

>      fprintf(stderr,"Trying to enter in raw mode... ");
>      if (brlapi_getRaw()<0)
>       brlapi_perror("brlapi_getRaw");
>      else {
>       fprintf(stderr,"Ok, leaving raw mode immediately\n");
>       brlapi_leaveRaw();
>      }

> `

Not every driver supports raw mode (actually only one does for the moment ;-), 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 !

## 4.5 Getting tty control

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_getTty(0,BRLCOMMANDS,NULL)>=0)
>      {
>       printf("Ok\n");

> `

The first parameter tells the server the number of the tty to take control of. Setting 0 lets the library determine it for us.

The server is asked to send brltty commands, which are device-independant. The last parameter might be used when binding keys. This is discussed in online manual pages.

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.

## 4.6 Writing something on the display

The application can now write things on the braille display without altering the screen display:

> `

>       fprintf(stderr,"Writing to braille display... ");
>       if (brlapi_writeBrl(0,"Press a braille key to continue...")>=0)
>       {
>        fprintf(stderr,"Ok\n");

> `

The cursor is also asked not 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.

## 4.7 Waiting for a key press

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_readCommand(1,&key)>0)
>         fprintf(stderr,"got it! (code=%d)\n",key);

> `

The command code is returned, as described in `<brltty/brldefs.h>`. It is not transmitted to brltty: 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.

## 4.8 Leaving tty control

Let's now leave the tty:

> `

>       fprintf(stderr,"Leaving tty... ");
>       if (brlapi_leaveTty()>=0)
>        fprintf(stderr,"Ok\n");

> `

But control of another tty can still be get for instance, by calling `brlapi_getTty()` again...

## 4.9 Disconnecting from BrlAPI

Let's disconnect from BrlAPI:

> `

>      brlapi_closeConnection();

> `

The application can as well still need to connect to another server on another computer for instance, by calling `brlapi_initializeConnection()` again...

## 4.10 Putting everything together...

> `

>     #include <stdio.h>
>     #include <stdlib.h>
>     #include <brltty/brlapi.h>

>     int main()
>     {
>      brl_keycode_t key;
>      char *p,*c;
>      int x, y;

>     /* Connect to BrlAPI */
>       if (brlapi_initializeConnection(NULL,NULL)<0)
>       {
>        brlapi_perror("brlapi_initializeConnection");
>        exit(1);
>       }

>     /* Get driver id & name */
>      p = brlapi_getDriverId();
>      if (!p)
>       brlapi_perror("brlapi_getDriverId");
>      else
>       printf("Driver id: %s\n",p);

>      p = brlapi_getDriverName();
>      if (!p)
>       brlapi_perror("brlapi_getDriverName");
>      else
>       printf("Driver name: %s\n",p);

>     /* Get display size */
>      if (brlapi_getDisplaySize(&x, &y)<0)
>       brlapi_perror("brlapi_getDisplaySize");
>      else
>       printf("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 */
>      printf("Trying to enter in raw mode... ");
>      if (brlapi_getRaw()<0)
>       brlapi_perror("brlapi_getRaw");
>      else {
>       printf("Ok, leaving raw mode immediately\n");
>       brlapi_leaveRaw();
>      }

>     /* Get tty control */
>      printf("Taking control of the tty... ");
>      if (brlapi_getTty(0,BRLCOMMANDS,NULL)>=0)
>      {
>       printf("Ok\n");

>     /* Write something on the display */
>       fprintf(stderr,"Writing to braille display... ");
>       if (brlapi_writeBrl(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_readCommand(1,&key)>0)
>         fprintf(stderr,"got it! (code=%d)\n",key);
>        else brlapi_perror("brlapi_readCommand");

>       } else brlapi_perror("brlapi_writeBrl");

>     /* Leave tty control */
>       fprintf(stderr,"Leaving tty... ");
>       if (brlapi_leaveTty()>=0)
>        fprintf(stderr,"Ok\n");
>       else brlapi_perror("brlapi_leaveTty");

>      } else brlapi_perror("brlapi_getTty");

>     /* Disconnect from BrlAPI */
>      brlapi_closeConnection();
>      return 0;
>     }

> `

This should compile well thanks to `gcc apiclient.c -o apiclient -lbrlapi`

Next Previous Contents