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-5.html (8.94 KB)      -rw-r--r--

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

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

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

5.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":"");

---

5.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!

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

---

The first parameter tells the server the number of the tty to take control of. Setting -1 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.

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

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

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

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

5.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(-1,NULL)>=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