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
|
<!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: Protocol reference</TITLE>
<LINK HREF="BrlAPI-5.html" REL=previous>
<LINK HREF="BrlAPI.html#toc6" REL=contents>
</HEAD>
<BODY>
Next
<A HREF="BrlAPI-5.html">Previous</A>
<A HREF="BrlAPI.html#toc6">Contents</A>
<HR>
<H2><A NAME="s6">6.</A> <A HREF="BrlAPI.html#toc6">Protocol reference</A></H2>
<P>Under some circumstances, it may be preferable to communicate directly with
<EM>BrlAPI</EM>'s server.avoid rather than using <EM>BrlAPI</EM>'s
library. Here are the needed details to be able
to do this. This chapter is also of interest if a precise understanding of
how the communication stuff works is desired, to be sure to understand how
to write multithreaded clients, for instance.</P>
<P>In all the following, <EM>integer</EM> will mean an unsigned 32 bits integer in
network byte order (ie most significant bytes first).</P>
<H2><A NAME="ss6.1">6.1</A> <A HREF="BrlAPI.html#toc6.1">Reliable packet transmission channel</A>
</H2>
<P>The protocol between <EM>BrlAPI</EM>'s server and clients is based on exchanges
of packets. So as to avoid locks due to packet loss, these exchanges are
supposed reliable, and ordering must be preserved, thus <EM>BrlAPI</EM> needs
a reliable packet transmission channel.</P>
<P>To achieve this, <EM>BrlAPI</EM> uses a TCP-based connection, on which packets
are transmitted this way:</P>
<P>
<UL>
<LI>the size in bytes of the packet is transmitted first as an integer,</LI>
<LI>then the type of the packet, as an integer,</LI>
<LI>and finally the packet data.</LI>
</UL>
</P>
<P>The size does not include the { size, type } header, so that packets which
don't need any data have a size of 0 byte. The type of the packet can be
either of <CODE>BRLPACKET_*</CODE> constants defined in <CODE>brlapi.h</CODE>. Each type of
packet will be further discussed below.</P>
<P><EM>BrlAPI</EM>'s library ships two functions to achieve packets sending and receiving
using this protocol: <CODE>brlapi_writePacket</CODE> and <CODE>brlapi_readPacket</CODE>. It
is a good idea to use instead of rewriting them, since this protocol
might change one day in favor of a real reliable packet transmission protocol
such as the experimental RDP.</P>
<H2><A NAME="ss6.2">6.2</A> <A HREF="BrlAPI.html#toc6.2">Responses from the server</A>
</H2>
<P>As described below, many packets are `acknowledged'. It means that upon
reception, the server sends either:</P>
<P>
<UL>
<LI>a <CODE>BRLPACKET_ACK</CODE> packet, with no data, which means the operation
corresponding to the received packet was successful,</LI>
<LI>or a <CODE>BRLPACKET_ERROR</CODE> packet, the data being an integer
which should be one of <CODE>BRLERR_*</CODE> constants. This
means the operation corresponding to the received packet failed.</LI>
</UL>
</P>
<P>Some other packets need some information as a response.
Upon reception, the server will send either:</P>
<P>
<UL>
<LI>a packet of the same type, its data being the response,</LI>
<LI>or a <CODE>BRLPACKET_ERROR</CODE> packet.</LI>
</UL>
</P>
<H2><A NAME="ss6.3">6.3</A> <A HREF="BrlAPI.html#toc6.3">Operating modes</A>
</H2>
<P>The connection between the client and the server can be in either of the
four following modes:</P>
<P>
<UL>
<LI>authentication mode: this is the initial mode, when the client hasn't
authenticated itself to the server yet. Only one <CODE>BRLPACKET_AUTHKEY</CODE> packet
will be accepted, which makes the connection enter normal mode;
</LI>
<LI>normal mode: the client is authenticated, but didn't ask for a tty
or raw mode. The client can send either of these types of packet:
<UL>
<LI><CODE>BRLPACKET_GETDRIVERID</CODE>, <CODE>BRLPACKET_GETDRIVERNAME</CODE>
or <CODE>BRLPACKET_GETDISPLAYSIZE</CODE> to get pieces of information from the server,</LI>
<LI><CODE>BRLPACKET_GETTTY</CODE> to enter tty handling mode,</LI>
<LI><CODE>BRLPACKET_GETRAW</CODE> to enter raw mode,</LI>
<LI><CODE>BRLPACKET_BYE</CODE> to tell the server it wants to close the connection.</LI>
</UL>
;
</LI>
<LI>tty handling mode: the client holds the control of a tty: <EM>brltty</EM> has
no power on it any more, masked keys excepted. It's up to the client to manage
display and keypresses. For this, it can send either of these types of packet:
<UL>
<LI><CODE>BRLPACKET_GETTTY</CODE> to switch to another tty, but how key presses
should be sent mustn't change,</LI>
<LI><CODE>BRLPACKET_LEAVETTY</CODE> to leave tty handling mode and go back to
normal mode,</LI>
<LI><CODE>BRLPACKET_MASKKEY</CODE> or <CODE>BRLPACKET_UNMASKKEY</CODE> to mask and unmask
keys,</LI>
<LI><CODE>BRLPACKET_WRITE</CODE> or <CODE>BRLPACKET_STATUSWRITE</CODE> to display text on
this tty,</LI>
<LI><CODE>BRLPACKET_GETRAW</CODE> to enter raw mode,</LI>
<LI><CODE>BRLPACKET_GETDRIVERID</CODE>, <CODE>BRLPACKET_GETDRIVERNAME</CODE>
or <CODE>BRLPACKET_GETDISPLAYSIZE</CODE> to get pieces of information from the server,</LI>
<LI><CODE>BRLPACKET_BYE</CODE> to tell the server it wants to close the connection.</LI>
</UL>
And the server might send either <CODE>BRLPACKET_KEY</CODE> or <CODE>BRLPACKET_COMMAND</CODE>
packets to signal key presses;
</LI>
<LI>raw mode: the client wants to exchange packets directly with the braille
terminal. Only these types of packet will be accepted:
<UL>
<LI><CODE>BRLPACKET_LEAVERAW</CODE> to get back to previous mode, either normal or
tty handling mode.</LI>
<LI><CODE>BRLPACKET_PACKET</CODE> to send a packet to the braille terminal.</LI>
<LI><CODE>BRLPACKET_BYE</CODE> to tell the server it wants to close the connection.</LI>
</UL>
And the server might send <CODE>BRLPACKET_PACKET</CODE> packets to give received packets
from the terminal to the client.</LI>
</UL>
</P>
<H2><A NAME="ss6.4">6.4</A> <A HREF="BrlAPI.html#toc6.4">Details for each type of packet</A>
</H2>
<P>Here is described the semantics of each type of packet. Most of them are
directly linked to some of <EM>BrlAPI</EM>'s library's functions. Reading their
online manual page as well will hence be of good help for understanding.</P>
<H3><CODE>BRLPACKET_AUTHKEY</CODE> (see <EM>brlapi_loadAuthKey()</EM>)</H3>
<P>This must be the first packet ever transmitted from the client to the
server. It lets the client authenticate itself to the server. Data is the
authentication key itself.</P>
<P>If the authentication key matches the servers', it is acknowledged, and
other types of packets might be used, other <CODE>BRLPACKET_AUTHKEY</CODE> shouldn't
be sent by the client.</P>
<P>If the authentication key doesn't match, the server sends a
<CODE>BRLERR_CONNREFUSED</CODE> and closes the connection.</P>
<H3><CODE>BRLPACKET_BYE</CODE> (see <EM>brlapi_closeConnection()</EM>)</H3>
<P>This should be sent by the client when it doesn't need server's services any
more, just before disconnecting from it. The server will acknowledge this
packet and close the connection. It will also clean up things like the tty which
was got by the application, as well as raw mode, by sending a special reset
event to the braille device, if the <CODE>brltty</CODE> driver implements it. But this
shouldn't prevent clients from cleanly leaving ttys and raw mode before issuing
<CODE>BRLPACKET_BYE</CODE> !</P>
<H3><CODE>BRLPACKET_GETDRIVERID</CODE> (see <EM>brlapi_getDriverId()</EM>)</H3>
<P>This should be sent by the client when it needs the 2-char identifier of
the current <CODE>brltty</CODE> driver. The returned string is \0 terminated.</P>
<H3><CODE>BRLPACKET_GETDRIVERNAME</CODE> (see <EM>brlapi_getDriverName()</EM>)</H3>
<P>This should be sent by the client when it needs the full name of
the current <CODE>brltty</CODE> driver. The returned string is \0 terminated.</P>
<H3><CODE>BRLPACKET_GETDISPLAYSIZE</CODE> (see <EM>brlapi_getDisplaySize()</EM>)</H3>
<P>This should be sent by the client when it needs to know the braille display
size. The returned data are two integers: width and then height.</P>
<H3><CODE>BRLPACKET_GETTTY</CODE> (see <EM>brlapi_getTty()</EM>)</H3>
<P>This should be sent by the client to get control of a tty. Sent data are
two integers: the number of the tty to get control of (it mustn't be 0), and
how key presses should be sent: either <CODE>BRLKEYCODES</CODE> or <CODE>BRLCOMMANDS</CODE>.
This packet is then acknowledged by the server.</P>
<H3><CODE>BRLPACKET_KEY</CODE> and <CODE>BRLPACKET_COMMAND</CODE> (see <EM>brlapi_readKey()</EM>and <EM>brlapi_readCommand()</EM>)</H3>
<P>As soon as the client got a tty, it must be prepared to handle either
<CODE>BRLPACKET_KEY</CODE> or <CODE>BRLPACKET_COMMAND</CODE> incoming packets (depending on the
parameter given in the <CODE>BRLPACKET_GETTTY</CODE> packet), at any time (as soon as
the key was pressed on the braille terminal, hopefuly).
The data holds the key press code
as an integer, either a raw key code in <CODE>BRLPACKET_KEY</CODE> packets, or a
<CODE>brltty</CODE> command code in <CODE>BRLPACKET_COMMAND</CODE> packets.</P>
<H3><CODE>BRLPACKET_LEAVETTY</CODE> (see <EM>brlapi_leaveTty()</EM>)</H3>
<P>This should be sent to free the tty and masked keys lists.
This is acknowledged by the server.</P>
<H3><CODE>BRLPACKET_MASKKEYS</CODE> and <CODE>BRLPACKET_UNMASKKEYS</CODE> (see<EM>brlapi_ignoreKeys()</EM> and <EM>brlapi_unignoreKeys()</EM>)</H3>
<P>If the client doesn't want every key press to be signaled to it, but some of
them to be given to <CODE>brltty</CODE> for normal processing, it can send
<CODE>BRLPACKET_MASKKEYS</CODE> packets to tell ranges of key codes which shouldn't be
sent to it, but given to <CODE>brltty</CODE>, and <CODE>BRLPACKET_UNMASKKEYS</CODE> packets
to tell ranges of key codes which should be sent to it, and not given to
<CODE>brltty</CODE>. The server keeps a dynamic list of ranges, so that arbitrary
sequences of such packets can be sent. Data are 2 integers: the lower and the
upper boundaries; lower and upper must be equal to tell one key, for instance.</P>
<H3><CODE>BRLPACKET_WRITE</CODE> (see <EM>brlapi_writeBrl()</EM>)</H3>
<P>To display text on the braille terminal and set the position of the cursor,
the client can send a <CODE>BRLPACKET_WRITE</CODE> packet. This packet holds the cursor
position as an integer, and then the text to display, one byte per
caracter.
The text must exactly fit the braille display, ie hold <EM>height</EM>*<EM>width</EM>
bytes, where <EM>height</EM> and <EM>width</EM> must be get by sending a
<CODE>BRLPACKET_GETDISPLAYSIZE</CODE> packet. Moreover, characters are expected to
be encoded in latin-1. This packet is acknowledged by the server.</P>
<H3><CODE>BRLPACKET_WRITEDOTS</CODE> (see <EM>brlapi_writeBrlDots()</EM>)</H3>
<P>Is used the same way as <CODE>BRLPACKET_WRITE</CODE>, the only difference being that
characters are encoded in braille dots.</P>
<H3><CODE>BRLPACKET_STATWRITE</CODE></H3>
<P>Some braille terminals have a special status display, whose text is independant
from normal display's. To display text on it, the client can send a
<CODE>BRLPACKET_STATWRITE</CODE> packet, just like <CODE>BRLPACKET_WRITE</CODE> packets.</P>
<H3><CODE>BRLPACKET_STATWRITEDOTS</CODE></H3>
<P>Is used the same way as <CODE>BRLPACKET_STATWRITE</CODE>, the only difference being that
characters are encoded in braille dots.</P>
<H3><CODE>BRLPACKET_GETRAW</CODE> (see <EM>brlapi_getRaw()</EM>)</H3>
<P>To enter raw mode, the client must send a <CODE>BRLPACKET_GETRAW</CODE> packet,
which is acknowledged. Once in raw mode, no other packet than
<CODE>BRLPACKET_LEAVERAW</CODE> or <CODE>BRLPACKET_PACKET</CODE> will be accepted. The data must
hold the special value <CODE>BRLRAW_MAGIC</CODE>: <CODE>0xdeadbeef</CODE>, to avoid erroneous
raw mode activating.</P>
<H3><CODE>BRLPACKET_LEAVERAW</CODE> (see <EM>brlapi_leaveRaw()</EM>)</H3>
<P>To leave raw mode, the client must send a <CODE>BRLPACKET_LEAVERAW</CODE> packet, which
is acknowledged.</P>
<H3><CODE>BRLPACKET_PACKET</CODE> (see <EM>brlapi_sendRaw()</EM> and<EM>brlapi_recvRaw()</EM>)</H3>
<P>While in raw mode, only <CODE>BRLPACKET_PACKET</CODE> packets can be exchanged between
the client and the server: to send a packet to the braille terminal, the
client merely sends a <CODE>BRLPACKET_PACKET</CODE> packet, its data being the packet to
send to the terminal. Whenever its receives a packet from the terminal, the
server does exactly the same, so that packet exchanges between the terminal and
the server are exactly reproduced between the server and the client.</P>
<P>Packets' content depend on the braille driver, so that the client should
check for its id or name thanks to a <CODE>BRLPACKET_GETDRIVERID</CODE> packet or
a <CODE>BRLPACKET_GETDRIVERNAME</CODE> packet, prior to sending any
<CODE>BRLPACKET_GETRAW</CODE> packet.</P>
<HR>
Next
<A HREF="BrlAPI-5.html">Previous</A>
<A HREF="BrlAPI.html#toc6">Contents</A>
</BODY>
</HTML>
|
