BossBey File Manager

Editing: BrlAPI-7.html

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
<HTML>
<HEAD>
 <META NAME="GENERATOR" CONTENT="LinuxDoc-Tools 0.9.72">
 <TITLE>BrlAPI Reference manual: Protocol reference</TITLE>
 <LINK HREF="BrlAPI-6.html" REL=previous>
 <LINK HREF="BrlAPI.html#toc7" REL=contents>
</HEAD>
<BODY>
Next
<A HREF="BrlAPI-6.html">Previous</A>
<A HREF="BrlAPI.html#toc7">Contents</A>
<HR>
<H2><A NAME="sec-protocol"></A> <A NAME="s7">7.</A> <A HREF="BrlAPI.html#toc7">Protocol reference</A></H2>

<P>Under some circumstances, it may be preferable to communicate directly with
<EM>BrlAPI</EM>'s server 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="ss7.1">7.1</A> <A HREF="BrlAPI.html#toc7.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>BRLAPI_PACKET_*</CODE> constants defined in <CODE>api_protocol.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 these functions rather than 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="ss7.2">7.2</A> <A HREF="BrlAPI.html#toc7.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>BRLAPI_PACKET_ACK</CODE> packet, with no data, which means the operation
corresponding to the received packet was successful,</LI>
<LI>or a <CODE>BRLAPI_PACKET_ERROR</CODE> packet, the data being an integer
which should be one of <CODE>BRLAPI_ERROR_*</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>BRLAPI_PACKET_ERROR</CODE> packet.</LI>
</UL>
</P>

<P>If at some point an ill-formed or non-sense packet is received by the server,
and <CODE>BRLAPI_PACKET_EXCEPTION</CODE> is returned, holding the guilty packet for
further analysis.</P>

<H2><A NAME="ss7.3">7.3</A> <A HREF="BrlAPI.html#toc7.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>authorization mode: this is the initial mode, when the client hasn't
got the authorization to use the server yet. The server first sends a
<CODE>BRLAPI_PACKET_VERSION</CODE> packet that announces the server version. The client
must send back a <CODE>BRLAPI_PACKET_VERSION</CODE> for announcing its own version too.
The server then sends a <CODE>BRLAPI_PACKET_AUTH</CODE> packet that announces
which authorization methods are allowed. The client can then send
<CODE>BRLAPI_PACKET_AUTH</CODE> packets, which makes the connection enter normal mode.
If no authorization is needed, the server can announce the <CODE>NONE</CODE> method, the
client then doesn't need to send a <CODE>BRLAPI_PACKET_AUTH</CODE> packet.

</LI>
<LI>normal mode: the client is authorized to use the server, but didn't ask for a tty
or raw mode. The client can send either of these types of packet:
<UL>
<LI><CODE>BRLAPI_PACKET_GETDRIVERNAME</CODE>
or <CODE>BRLAPI_PACKET_GETDISPLAYSIZE</CODE> to get pieces of information from the server,</LI>
<LI><CODE>BRLAPI_PACKET_ENTERTTY</CODE>MODE to enter tty handling mode,</LI>
<LI><CODE>BRLAPI_PACKET_ENTERRAWMODE</CODE> to enter raw mode,</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>BRLAPI_PACKET_ENTERTY</CODE>MODE to switch to another tty, but how key presses
should be sent mustn't change,</LI>
<LI><CODE>BRLAPI_PACKET_LEAVETTYMODE</CODE> to leave tty handling mode and go back to
normal mode,</LI>
<LI><CODE>BRLAPI_PACKET_IGNOREKEYRANGE</CODE> and <CODE>BRLAPI_PACKET_ACCEPTKEYRANGE</CODE> to mask and unmask keys,</LI>
<LI><CODE>BRLAPI_PACKET_WRITE</CODE> to display text on this tty,</LI>
<LI><CODE>BRLAPI_PACKET_ENTERRAWMODE</CODE> to enter raw mode,</LI>
<LI><CODE>BRLAPI_PACKET_GETDRIVERNAME</CODE>
or <CODE>BRLAPI_PACKET_GETDISPLAYSIZE</CODE> to get pieces of information from the server,</LI>
</UL>

And the server might send <CODE>BRLAPI_PACKET_KEY</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>BRLAPI_PACKET_LEAVERAWMODE</CODE> to get back to previous mode, either normal or
tty handling mode.</LI>
<LI><CODE>BRLAPI_PACKET_PACKET</CODE> to send a packet to the braille terminal.</LI>
</UL>

And the server might send <CODE>BRLAPI_PACKET_PACKET</CODE> packets to give received packets
from the terminal to the client.
</LI>
<LI>suspend mode: the client wants to completely drive the braille terminal.
The device driver is hence kept closed. No type of packet is allowed except
<CODE>BRLAPI_PACKET_RESUME</CODE></LI>
</UL>
</P>
<P>Termination of the connection is initiated by the client in normal mode by
simply closing its side of the socket. The server will then close the
connection.</P>

<H2><A NAME="ss7.4">7.4</A> <A HREF="BrlAPI.html#toc7.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>BRLAPI_PACKET_VERSION</CODE>This must be the first packet ever transmitted from the server to the client and from the client to the server. The server sends one first for letting the client know its protocol version. Data is an integer indicating the protocol version. Then client must then respond the same way for giving its version.  If the protocol version can't be handled by the server, a <CODE>BRLAPI_ERROR_PROTOCOL_VERSION</CODE> error packet is returned and the connection is closed.</H3>

<H3><CODE>BRLAPI_PACKET_AUTH</CODE></H3>

<P>This must be the second packet ever transmitted from the server to the client
and from the client to the server. The server sends one first for letting the
client know which authorization methods are available.  Data is the allowed
authorization types, as integers.</P>
<P>If the <CODE>NONE</CODE> method is not announced by the server, the client can then try
to get authorized by sending packets whose data is the type of authorization
that is tried (as an integer), and eventually some data (if the authorization
type needs it).</P>
<P>If the authorization is successful, the server acknowledges the packet, and
other types of packets might be used, other <CODE>BRLAPI_PACKET_AUTH</CODE> shouldn't be
sent by the client.</P>
<P>If the authorization is not successful, the server sends a
<CODE>BRLAPI_ERROR_AUTHENTICATION</CODE> error, and the client can try another
authorization method.</P>
<P>Authorization methods are as follow:</P>
<P>
<UL>
<LI><CODE>NONE</CODE>: the client doesn't need to send an authorization packet.</LI>
<LI><CODE>KEY</CODE>: data holds a secret key, the authorization is successful only
if the key matches the server secret key.</LI>
<LI><CODE>CREDENTIALS</CODE>: Operating-System-specific credentials are explicitely
sent over the socket, the authorization is successful if the server considers
the credentials sufficient.</LI>
</UL>
</P>
<P>Note: when the Operating system permits it, the server may use implicit
credential check, and then advertise the <CODE>none</CODE> method.</P>

<H3><CODE>BRLAPI_PACKET_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>BRLAPI_PACKET_GETMODELID</CODE> (see <EM>brlapi_getModelIdentifier()</EM>)</H3>

<P>This should be sent by the client when it needs to identify
which model of braille display is currently used by <CODE>brltty</CODE>.
The returned string is \0 terminated.</P>

<H3><CODE>BRLAPI_PACKET_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>BRLAPI_PACKET_ENTERTTYMODE</CODE> (see <EM>brlapi_enterTtyMode()</EM> and <EM>brlapi_enterTtyModeWithPath()</EM>)</H3>

<P>This should be sent by the client to get control of a tty. Sent data are
first a series of integers: the first one gives the number of following
integers, which are the numbers of ttys that leads to the tty that
the application wants to take control of (it can be empty if the tty is 
one of the machine's VT). The last integer of this series tells the number of
the tty to get control of. Finaly, how key presses should be reported is sent:
either a driver name or "", preceded by the number of caracters in the driver
name (0 in the case of ""), as an unsigned byte. This packet is then
acknowledged by the server.</P>

<H3><CODE>BRLAPI_PACKET_KEY</CODE> (see <EM>brlapi_readKey()</EM>)</H3>

<P>As soon as the client gets a tty, it must be prepared to handle
<CODE>BRLAPI_PACKET_KEY</CODE> incoming packets
at any time (as soon as the key
was pressed on the braille terminal, hopefuly).
The data holds a key code as 2 integers, or
the key flags then the command code
as 2 integers, depending on what has been request in the
<CODE>BRLAPI_PACKET_ENTERTTYMODE</CODE> packet.</P>

<H3><CODE>BRLAPI_PACKET_SETFOCUS</CODE> (see <EM>brlapi_setFocus()</EM>)</H3>

<P>For the server to know which tty is active, one particular client is responsible
for sending <CODE>BRLAPI_PACKET_SETFOCUS</CODE> packets. They hold a single integer telling
the new current tty. For instance, when running an X server on VT 7, the
<CODE>xbrlapi</CODE> client would have sent a <CODE>BRLAPI_PACKET_ENTERTTYMODE(7)</CODE> and will send
window IDs whenever X focus changes, allowing display and keypresses switching
between xterms.</P>

<H3><CODE>BRLAPI_PACKET_LEAVETTYMODE</CODE> (see <EM>brlapi_leaveTtyMode()</EM>)</H3>

<P>This should be sent to free the tty and masked keys lists.
This is acknowledged by the server.</P>

<H3><CODE>BRLAPI_PACKET_IGNOREKEYRANGE</CODE> and <CODE>BRLAPI_PACKET_ACCEPTKEYRANGE</CODE>(see <EM>brlapi_ignoreKeyRange()</EM> and <EM>brlapi_acceptKeyRange()</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>BRLAPI_PACKET_IGNOREKEYRANGE</CODE> packets to
tell ranges of key codes which shouldn't be
sent to it, but given to <CODE>brltty</CODE>, and <CODE>BRLAPI_PACKET_ACCEPTKEYRANGE</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.
For ranges, Data are 2 pairs of integers: the lower and the
upper boundaries; lower and upper must be equal to tell one key, for instance.
For Sets, Data simply consists of pairs of integers, one per key in the set.</P>

<H3><CODE>BRLAPI_PACKET_WRITE</CODE> (see <EM>brlapi_write()</EM>)</H3>

<P>To display text on the braille terminal and set the position of the cursor,
the client can send a <CODE>BRLAPI_PACKET_WRITE</CODE> packet. The packet begins
with an integer holding flags (see <CODE>BRLAPI_WF_*</CODE>). These flags indicate
which data will then be available, in the following order (corresponding to
flag weight):</P>
<P>
<UL>
<LI> A display number can be given as a integer, in case the braille
display has several. If not given, usual display is used.</LI>
<LI> A region must be given as two integers indicating the beginning and the
number of characters of the part of the braille display which is to be updated,
the first cell of the display being numbered 1.</LI>
<LI> The text to display can then be given, preceded by its size in bytes
expressed as an integer. It will erase the corresponding region in the AND and
OR fields. The text's length in characters must exactly match the region
size. For multibyte text, this is the number of wide characters. Notably,
combining and double-width characters count for 1.</LI>
<LI> Then an AND field can be given, one byte per character: the 8-dot
representation of the above text will be AND-ed with this field, hence allowing
to erase some unwanted parts of characters. Dots are coded as described in
ISO/TR 11548-1: dot 1 is set iff bit 0 is set, dot 2 is set iff bit 1 is set,
...  dot <EM>i+1</EM> is set if bit <EM>i</EM> is set. This also corresponds to the
low-order byte of the coding of unicode's braille row <CODE>U+2800</CODE>.</LI>
<LI> As well, an OR field may be given, one byte per character: the 8-dot
result of the AND operation above (or the 8-dot representation of the text if
no AND operation was performed) is OR-ed with this field, hence allowing
to set some dots, to underline characters for instance.</LI>
<LI> A cursor position can be specified. 1 representing
the first character of the display, 0 turning the cursor off. If not given,
the cursor (if any) is left unmodified.</LI>
<LI> Last but not least, the charset of the text can be specified: the length
of the name first in one byte, then the name itself in ASCII characters. If the
charset is not specified, an 8-bit charset is assumed, and it is assumed to be
the same as the server's. Multibyte charsets may be used, AND and OR fields'
bytes will correspond to each text's wide <EM>character</EM>, be it a combining or a
double-width character.</LI>
</UL>
</P>
<P>A <CODE>BRLAPI_PACKET_WRITE</CODE> packet without any flag (and hence no data) means a
"void" WRITE: the server clears the output buffer for this connection.</P>

<H3><CODE>BRLAPI_PACKET_ENTERRAWMODE</CODE> (see <EM>brlapi_enterRawMode()</EM>)</H3>

<P>To enter raw mode, the client must send a <CODE>BRLAPI_PACKET_ENTERRAWMODE</CODE> packet,
which is acknowledged. Once in raw mode, no other packet than
<CODE>BRLAPI_PACKET_LEAVERAWMODE</CODE> or <CODE>BRLAPI_PACKET_PACKET</CODE> will be accepted.
The data must hold the special value <CODE>BRLAPI_DEVICE_MAGIC</CODE>: <CODE>0xdeadbeef</CODE>, then
the name of the driver (one byte for the length, then the name) to avoid
erroneous raw mode activating.</P>

<H3><CODE>BRLAPI_PACKET_LEAVERAWMODE</CODE> (see <EM>brlapi_leaveRawMode()</EM>)</H3>

<P>To leave raw mode, the client must send a <CODE>BRLAPI_PACKET_LEAVERAWMODE</CODE> packet, which
is acknowledged.</P>

<H3><CODE>BRLAPI_PACKET_PACKET</CODE> (see <EM>brlapi_sendRaw()</EM> and <EM>brlapi_recvRaw()</EM>)</H3>

<P>While in raw mode, only <CODE>BRLAPI_PACKET_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>BRLAPI_PACKET_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>

<H3><CODE>BRLAPI_PACKET_SUSPENDDRIVER</CODE> (see <EM>brlapi_suspendDriver()</EM>)</H3>

<P>To enter suspend mode, the client must send a <CODE>BRLAPI_PACKET_SUSPEND</CODE> packet,
which is acknowledge. Once in suspend mode, no other packet than
<CODE>BRLAPI_PACKET_RESUME</CODE> will be accepted.
The data must hold the special value <CODE>BRLAPI_DEVICE_MAGIC</CODE>: <CODE>0xdeadbeef</CODE>,
then the name of the driver (one byte for the length, then the name) to avoid
erroneous raw mode activating.</P>

<H3><CODE>BRLAPI_PACKET_PARAM_REQUEST</CODE></H3>

<P>This packet is sent by the client to request values of parameters. The packet
begins with an integer which holds flags (see <CODE>BRLAPI_PARAMF_*</CODE>) which
describe which, how, and when the value should be returned by the server:
<UL>
<LI> When the <CODE>BRLAPI_PARAMF_GLOBAL</CODE> flag is set, the server will
return/subscribe the global value instead of the local value.</LI>
<LI> When the <CODE>BRLAPI_PARAMF_GET</CODE> flag is set, the server acknowledges the
request by returning the latest value with a <CODE>BRLAPI_PACKET_PARAM_VALUE</CODE>
packet. Otherwise the server acknowledges the request with a
<CODE>BRLAPI_PACKET_ACK</CODE> packet, without providing the value.</LI>
<LI> When the <CODE>BRLAPI_PARAMF_SUBSCRIBE</CODE> flag is set, the server will keep
sending asynchronously the value of the parameter whenever it changes, with
<CODE>BRLAPI_PACKET_PARAM_UPDATE</CODE> packets, until
another request packet has the <CODE>BRLAPI_PARAMF_UNSUBSCRIBE</CODE> flag set for this
parameter.</LI>
<LI> When the <CODE>BRLAPI_PARAMF_SELF</CODE> flag is set along
<CODE>BRLAPI_PARAMF_SUBSCRIBE</CODE>, the server will send the value of the parameter
when it is changed even by the client itself.</LI>
<LI> When the <CODE>BRLAPI_PARAMF_UNSUBSCRIBE</CODE> flag is set, the server
will stop sending asynchronously the value of the parameter with
<CODE>BRLAPI_PACKET_PARAM_UPDATE</CODE> packets.</LI>
</UL>
</P>
<P>It does not make sense to set both the <CODE>BRLAPI_PARAMF_SUBSCRIBE</CODE> and
<CODE>BRLAPI_PARAMF_UNSUBSCRIBE</CODE> flags.</P>
<P>Then an integer representing the parameter to be requested.
Then two integers that form (in big-endian order) a 64bit value used to
subspecify the precise parameter to be requested (e.g. a keycode number).</P>
<P>If several <CODE>BRLAPI_PARAMF_SUBSCRIBE</CODE> packets are sent by the client, as
many <CODE>BRLAPI_PARAMF_UNSUBSCRIBE</CODE> packets have to be sent by the client before
the server stops sending <CODE>BRLAPI_PACKET_PARAM_UPDATE</CODE> packets.</P>

<H3><CODE>BRLAPI_PACKET_PARAM_VALUE</CODE></H3>

<P>This packet is sent by the client or the server to provide the value of a
parameter. The packet begins with an integer which holds flags (see
<CODE>BRLAPI_PVF_*</CODE>) which describe which value is being transmitted:</P>
<P>
<UL>
<LI> When the <CODE>BRLAPI_PVF_GLOBAL</CODE> flag is set, the value is the global value
instead of the local value.</LI>
</UL>
</P>
<P>Then an integer representing the parameter being transmitted. Then two integers
that form (in big-endian order) a 64bit value used to subspecify the precise
parameter being transmitted (e.g. a keycode number).  Eventually, the packet
contains the value.</P>
<P>When the packet is sent by the client, it defines the new value of the
parameter, and if it is a global value, the server broadcasts the new value to
all clients which have subscribed to updates. The packet is then acknowledged by
the server on success. If the value can not be changed, the server returns an
error (e.g. <CODE>BRLAPI_ERROR_READONLY_PARAMETER</CODE>).</P>

<H3><CODE>BRLAPI_PACKET_PARAM_VALUE</CODE>This packet is sent asynchronously by the server to provide an update of a value of a parameter. This is sent only if the client has previously sent a <CODE>BRLAPI_PACKET_PARAM_REQUEST</CODE> packet with the <CODE>BRLAPI_PARAMF_SUBSCRIBE</CODE>for the corresponding parameter. It is structured exactly like a <CODE>BRLAPI_PACKET_PARAM_VALUE</CODE> packet.</H3>

<HR>
Next
<A HREF="BrlAPI-6.html">Previous</A>
<A HREF="BrlAPI.html#toc7">Contents</A>
</BODY>
</HTML>

Cancel