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
|
<!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: Introduction</TITLE>
<LINK HREF="BrlAPI-2.html" REL=next>
<LINK HREF="BrlAPI.html#toc1" REL=contents>
</HEAD>
<BODY>
<A HREF="BrlAPI-2.html">Next</A>
Previous
<A HREF="BrlAPI.html#toc1">Contents</A>
<HR>
<H2><A NAME="s1">1.</A> <A HREF="BrlAPI.html#toc1">Introduction</A></H2>
<P><EM>BrlAPI</EM> is a service provided by the <EM>brltty</EM> daemon.</P>
<P>Its purpose is to allow programmers to write applications that take advantage
of a braille terminal in order to deliver a blind user suitable information
for his/her specific needs.</P>
<P>While an application communicates with the braille terminal, everything
<EM>brltty</EM> sends to the braille terminal in the application's console is
ignored, whereas each piece of data coming from the braille terminal is sent to
the application, rather than to <EM>brltty</EM>.</P>
<H2><A NAME="ss1.1">1.1</A> <A HREF="BrlAPI.html#toc1.1">Concepts</A>
</H2>
<P> All throughout this manual, a few terms will be used which are either
specific to braille terminals, or introduced because of <EM>BrlAPI</EM>. They are defined
below. Taking a few minutes to go through this glossary will save a lot
of time and questions later.</P>
<P>
<DL>
<DT><B>Authentication key</B><DD><P>A file containing arbitrary data, that has to be sent to the server by the
client, to prove it is allowed to establish a connection and then control
the braille terminal.</P>
<DT><B>Braille display</B><DD><P>The small screen on the braille terminal that is able to display braille text.</P>
<DT><B>Braille keyboard</B><DD><P>The keyboard of the braille terminal.</P>
<DT><B>Braille terminal</B><DD><P>A computer designed to display text in braille. In this case, the text is
supposed to come from another computer running Linux or any other Unix system.</P>
<DT><B>Brltty</B><DD><P>The background process that gives a blind person access to the Linux console
thanks to a braille terminal or speech synthetizer.</P>
<DT><B>Client</B><DD><P>An application designed to handle a braille terminal thanks to <EM>BrlAPI</EM>.</P>
<DT><B>Command</B><DD><P>A code returned by the driver, indicating an action do to, for instance
"go to previous line", "go to next line", etc.</P>
<DT><B>Driver</B><DD><P>A library that has functions to communicate with a braille terminal.
Basically, a driver has functions to open communication with the
braille terminal, close the communication, write on the braille
display, and read keypresses from the braille keyboard, plus some special
functions that will be described in detail in this manual.</P>
<DT><B>Key</B><DD><P>A code that is returned by the driver when a key is pressed. This is
different from a command, because the command concept is driver-independent
(all drivers use the same command codes - those defined by <EM>brltty</EM>), whereas
codes used for returning keypresses may vary between drivers.</P>
<DT><B>BrlAPI's Library</B><DD><P>This library helps clients to connect and use <EM>BrlAPI</EM>'s
server thanks to a series of <CODE>brlapi_</CODE>-prefixed functions.</P>
<DT><B>Packet</B><DD><P>A sequence of bytes making up the atomic unit in communications, either between
braille drivers and braille terminals or between the server and clients.</P>
<DT><B>Raw mode</B><DD><P>Mode in which the client application exchanges packets with the driver.
Normal operations like sending text for display or reading keypresses are
not available in this mode. It lets applications take advantage of advanced
functionalities of the driver's communication protocol.</P>
<DT><B>Server</B><DD><P>The part of <EM>brltty</EM> that controls incoming connections and communication
between clients and braille drivers.</P>
</DL>
</P>
<H2><A NAME="ss1.2">1.2</A> <A HREF="BrlAPI.html#toc1.2">How to read this manual</A>
</H2>
<P>This manual is split in five parts.</P>
<P>
<DL>
<DT><B>General description</B><DD><P>Describes more precisely what <EM>BrlAPI</EM>
is and how it works in collaboration with <EM>brltty</EM>'s core, the braille driver
and clients. In this part, a "connection-use-disconnection" scenario
will be described step by step, explaining for each step what <EM>BrlAPI</EM> does in
reaction to client instructions. These explanations will take place at a
user level.</P>
<DT><B>Installation and configuration</B><DD><P>This part explains in detail how to install and configure the API. For
instructions on how to install and configure <EM>brltty</EM>, please report to
the <EM>brltty</EM> documentation.</P>
<DT><B>Library description</B><DD><P>This part describes how client applications
can communicate with the server using the <EM>BrlAPI</EM> library that
comes with <EM>brltty</EM>. Each function will be briefly described,
classified by categories. More exhaustive descriptions of every
function are available in the corresponding online manual pages.</P>
<DT><B>Writing braille drivers</B><DD><P>This part describes how the braille drivers included in <EM>brltty</EM> should be
written in order to take advantage of <EM>BrlAPI</EM>'s services.</P>
<DT><B>Protocol reference</B><DD><P>This part describes in detail the communication
protocol that is used to communicate between server and clients.</P>
</DL>
</P>
<P>What should be read probably depends on what should be done by applications with
<EM>BrlAPI</EM>.</P>
<P>Reading chapters 2 and 3 is recommanded, since they provide useful
information and (hopefully) lead to a good understanding of <EM>BrlAPI</EM>,
for an efficient use.</P>
<P>Chapter 4 concerns writing applications that take advantage of
braille terminals so as to bring specific (and more useful) information to
blind people.</P>
<P>Chapter 5 is for braille driver implementation: either adding a braille driver
to <EM>brltty</EM> or modifying an existing one so that it can benefit from
<EM>BrlAPI</EM>'s features, this chapter will be of interest, since it describes
exactly what is needed to write a driver for <EM>brltty</EM>: the core
of drivers interface for instance.</P>
<P>Finally, Chapter 6 is for <EM>not using</EM> the library, but using the <EM>BrlAPI</EM>
server directly, when the library might not be sufficient: it describes the
underlying protocol that will have to be used to do so.</P>
<HR>
<A HREF="BrlAPI-2.html">Next</A>
Previous
<A HREF="BrlAPI.html#toc1">Contents</A>
</BODY>
</HTML>
|
