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:

> `

>      unsigned char id[3], name[21];
>      if (brlapi_getDriverId(id, sizeof(id))<0) {
>        brlapi_perror("getDriverId");
>      } else printf("Driver id: %s\n",id);
>      if (brlapi_getDriverName(name, sizeof(name))<0) {
>        brlapi_perror("getDriverName");

> `

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)>=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-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.

## 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_writeText(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_readKey(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/api.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)>=0)
>      {
>       printf("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)
>         fprintf(stderr,"got it! (code=%d)\n",key);
>        else brlapi_perror("brlapi_readKey");

>       } else brlapi_perror("brlapi_writeText");

>     /* 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