1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
|
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
<HTML>
<HEAD>
<META NAME="GENERATOR" CONTENT="LinuxDoc-Tools 0.9.20">
<TITLE>BrlAPI Reference manual: Library description</TITLE>
<LINK HREF="BrlAPI-5.html" REL=next>
<LINK HREF="BrlAPI-3.html" REL=previous>
<LINK HREF="BrlAPI.html#toc4" REL=contents>
</HEAD>
<BODY>
<A HREF="BrlAPI-5.html">Next</A>
<A HREF="BrlAPI-3.html">Previous</A>
<A HREF="BrlAPI.html#toc4">Contents</A>
<HR>
<H2><A NAME="s4">4.</A> <A HREF="BrlAPI.html#toc4">Library description</A></H2>
<P>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.</P>
<P>The historical test program for <EM>BrlAPI</EM> was something like:
<UL>
<LI>connect to <EM>BrlAPI</EM></LI>
<LI>get driver id</LI>
<LI>get driver name</LI>
<LI>get display size</LI>
<LI>try entering raw mode, immediately leave raw mode.</LI>
<LI>get tty control</LI>
<LI>write something on the display</LI>
<LI>wait for a key press</LI>
<LI>leave tty control</LI>
<LI>disconnect from <EM>BrlAPI</EM></LI>
</UL>
</P>
<P>It is here rewritten, its working briefly explained.</P>
<H2><A NAME="ss4.1">4.1</A> <A HREF="BrlAPI.html#toc4.1">Connecting to <EM>BrlAPI</EM></A>
</H2>
<P>Connection to <EM>BrlAPI</EM> is needed first, thanks to the
<CODE>brlapi_initializeConnection</CODE> call. For this, a
<CODE>brlapi_settings_t</CODE> variable must be filled which will hold the
settings the library needs to connect to the server. Just giving <CODE>NULL</CODE>
will work for local use. The other parameter lets you get back the parameters
which were actually used to initialize connection. <CODE>NULL</CODE> will also be nice
for now.</P>
<P>
<BLOCKQUOTE><CODE>
<HR>
<PRE>
if (brlapi_initializeConnection(NULL,NULL)<0)
{
brlapi_perror("brlapi_initializeConnection");
exit(1);
}
</PRE>
<HR>
</CODE></BLOCKQUOTE>
</P>
<P>The connection might fail, so testing is needed.</P>
<H2><A NAME="ss4.2">4.2</A> <A HREF="BrlAPI.html#toc4.2">Getting driver id and name</A>
</H2>
<P>Knowing the type of the braille device might be useful (<CODE>p</CODE> is defined as
<CODE>char *</CODE>):</P>
<P>
<BLOCKQUOTE><CODE>
<HR>
<PRE>
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);
</PRE>
<HR>
</CODE></BLOCKQUOTE>
</P>
<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.</P>
<H2><A NAME="ss4.3">4.3</A> <A HREF="BrlAPI.html#toc4.3">Getting display size</A>
</H2>
<P>Before writing on the braille display, the size should be always first
checked to be sure everything will hold on it:</P>
<P>
<BLOCKQUOTE><CODE>
<HR>
<PRE>
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":"");
</PRE>
<HR>
</CODE></BLOCKQUOTE>
</P>
<H2><A NAME="ss4.4">4.4</A> <A HREF="BrlAPI.html#toc4.4">Entering raw mode, immediately leaving raw mode.</A>
</H2>
<P>Entering raw mode is very simple:</P>
<P>
<BLOCKQUOTE><CODE>
<HR>
<PRE>
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();
}
</PRE>
<HR>
</CODE></BLOCKQUOTE>
</P>
<P>Not every driver supports raw mode (actually only one does for the moment ;-),
so testing is needed.</P>
<P>While in raw mode, <CODE>brlapi_sendRaw</CODE> and <CODE>brlapi_recvRaw</CODE>
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 !</P>
<H2><A NAME="ss4.5">4.5</A> <A HREF="BrlAPI.html#toc4.5">Getting tty control</A>
</H2>
<P>Let's now display something on the device. control of the tty must be get
first:</P>
<P>
<BLOCKQUOTE><CODE>
<HR>
<PRE>
fprintf(stderr,"Taking control of the tty... ");
if (brlapi_getTty(0,BRLCOMMANDS,NULL)>=0)
{
printf("Ok\n");
</PRE>
<HR>
</CODE></BLOCKQUOTE>
</P>
<P>The first parameter tells the server the number of the tty to take
control of. Setting 0 lets the library determine it for us.</P>
<P>The server is asked to send <EM>brltty</EM> commands, which are device-independant.
The last parameter might be used when binding keys. This is discussed in
online manual pages.</P>
<P>Getting control might fail if, for instance, another application already took
control of this tty, so testing is needed.</P>
<P>From now on, the braille display is detached from the screen.</P>
<H2><A NAME="ss4.6">4.6</A> <A HREF="BrlAPI.html#toc4.6">Writing something on the display</A>
</H2>
<P>The application can now write things on the braille display without
altering the screen display:</P>
<P>
<BLOCKQUOTE><CODE>
<HR>
<PRE>
fprintf(stderr,"Writing to braille display... ");
if (brlapi_writeBrl(0,"Press a braille key to continue...")>=0)
{
fprintf(stderr,"Ok\n");
</PRE>
<HR>
</CODE></BLOCKQUOTE>
</P>
<P>The cursor is also asked <EM>not</EM> to be shown: its position is set to 0.</P>
<P>"Writing to braille display... Ok" is now displayed on the screen, and
"Press a braille key to continue..." on the braille display.</P>
<H2><A NAME="ss4.7">4.7</A> <A HREF="BrlAPI.html#toc4.7">Waiting for a key press</A>
</H2>
<P>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:</P>
<P>
<BLOCKQUOTE><CODE>
<HR>
<PRE>
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);
</PRE>
<HR>
</CODE></BLOCKQUOTE>
</P>
<P>The command code is returned, as described in <CODE><brltty/brldefs.h></CODE>.
It is not transmitted to <EM>brltty</EM>: it is up to the application to define
the behavior, here cleanly exitting, as described below.</P>
<P>The first parameter tells the lib to block until a key press is indeed read.</P>
<H2><A NAME="ss4.8">4.8</A> <A HREF="BrlAPI.html#toc4.8">Leaving tty control</A>
</H2>
<P>Let's now leave the tty:</P>
<P>
<BLOCKQUOTE><CODE>
<HR>
<PRE>
fprintf(stderr,"Leaving tty... ");
if (brlapi_leaveTty()>=0)
fprintf(stderr,"Ok\n");
</PRE>
<HR>
</CODE></BLOCKQUOTE>
</P>
<P>But control of another tty can still be get for instance, by calling
<CODE>brlapi_getTty()</CODE> again...</P>
<H2><A NAME="ss4.9">4.9</A> <A HREF="BrlAPI.html#toc4.9">Disconnecting from <EM>BrlAPI</EM></A>
</H2>
<P>Let's disconnect from <EM>BrlAPI</EM>:</P>
<P>
<BLOCKQUOTE><CODE>
<HR>
<PRE>
brlapi_closeConnection();
</PRE>
<HR>
</CODE></BLOCKQUOTE>
</P>
<P>The application can as well still need to connect to another server on another
computer for instance, by calling <CODE>brlapi_initializeConnection()</CODE>
again...</P>
<H2><A NAME="ss4.10">4.10</A> <A HREF="BrlAPI.html#toc4.10">Putting everything together...</A>
</H2>
<P>
<BLOCKQUOTE><CODE>
<HR>
<PRE>
#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;
}
</PRE>
<HR>
</CODE></BLOCKQUOTE>
</P>
<P>This should compile well thanks to
<CODE>gcc apiclient.c -o apiclient -lbrlapi</CODE></P>
<HR>
<A HREF="BrlAPI-5.html">Next</A>
<A HREF="BrlAPI-3.html">Previous</A>
<A HREF="BrlAPI.html#toc4">Contents</A>
</BODY>
</HTML>
|
