1BrlAPI's protocol(3) BrlAPI BrlAPI's protocol(3)
2
6 BrlAPI's protocol - Instructions and constants for BrlAPI 's protocol.
7 Data Structures
10 struct brlapi_header_t
11 struct brlapi_versionPacket_t
12 struct brlapi_authClientPacket_t
13 struct brlapi_authServerPacket_t
14 struct brlapi_errorPacket_t
15 struct brlapi_getDriverSpecificModePacket_t
16 struct brlapi_writeArgumentsPacket_t
17 union brlapi_packet_t
18 Defines
20 #define BRLAPI_PROTOCOL_VERSION ((uint32_t) 8)
21 #define BRLAPI_MAXPACKETSIZE 512
22 #define BRLAPI_PACKET_VERSION 'v'
23 #define BRLAPI_PACKET_AUTH 'a'
24 #define BRLAPI_PACKET_GETDRIVERNAME 'n'
25 #define BRLAPI_PACKET_GETDISPLAYSIZE 's'
26 #define BRLAPI_PACKET_ENTERTTYMODE 't'
27 #define BRLAPI_PACKET_SETFOCUS 'F'
28 #define BRLAPI_PACKET_LEAVETTYMODE 'L'
29 #define BRLAPI_PACKET_KEY 'k'
30 #define BRLAPI_PACKET_IGNOREKEYRANGES 'm'
31 #define BRLAPI_PACKET_ACCEPTKEYRANGES 'u'
32 #define BRLAPI_PACKET_WRITE 'w'
33 #define BRLAPI_PACKET_ENTERRAWMODE '*'
34 #define BRLAPI_PACKET_LEAVERAWMODE '#'
35 #define BRLAPI_PACKET_PACKET 'p'
36 #define BRLAPI_PACKET_ACK 'A'
37 #define BRLAPI_PACKET_ERROR 'e'
38 #define BRLAPI_PACKET_EXCEPTION 'E'
39 #define BRLAPI_PACKET_SUSPENDDRIVER 'S'
40 #define BRLAPI_PACKET_RESUMEDRIVER 'R'
41 #define BRLAPI_DEVICE_MAGIC [22m(0xdeadbeefL)
42 #define BRLAPI_HEADERSIZE sizeof(brlapi_header_t)
43 #define BRLAPI_AUTH_NONE 'N'
44 #define BRLAPI_AUTH_KEY 'K'
45 #define BRLAPI_AUTH_CRED 'C'
46 #define BRLAPI_WF_DISPLAYNUMBER 0X01
47 #define BRLAPI_WF_REGION 0X02
48 #define BRLAPI_WF_TEXT 0X04
49 #define BRLAPI_WF_ATTR_AND 0X08
50 #define BRLAPI_WF_ATTR_OR 0X10
51 #define BRLAPI_WF_CURSOR 0X20
52 #define BRLAPI_WF_CHARSET 0X40
53 Functions
55 ssize_t brlapi_writePacket (brlapi_fileDescriptor fd,
56 brlapi_packetType_t type, const void *buf, size_t size)
57 ssize_t brlapi_readPacketHeader (brlapi_fileDescriptor fd,
58 brlapi_packetType_t *packetType)
59 ssize_t brlapi_readPacketContent (brlapi_fileDescriptor fd, size_t
60 packetSize, void *buf, size_t bufSize)
61 ssize_t brlapi_readPacket (brlapi_fileDescriptor fd,
62 brlapi_packetType_t *type, void *buf, size_t size)
63 Variables
65 pthread_mutex_t brlapi_fd_mutex
66
68 These are defines for the protocol between BrlAPI 's server and
69 clients. Understanding is not needed to use the BrlAPI library, so
70 reading this is not needed unless really wanting to connect to BrlAPI
71 without BrlAPI 's library.
72
74 #define BRLAPI_AUTH_CRED 'C'
75 Explicit socket credentials authorization
76 #define BRLAPI_AUTH_KEY 'K'
78 Key authorization
79 #define BRLAPI_AUTH_NONE 'N'
81 No or implicit authorization
82 #define BRLAPI_DEVICE_MAGIC (0xdeadbeefL)
84 Magic number to give when sending a BRLPACKET_ENTERRAWMODE or
85 BRLPACKET_SUSPEND packet
86 #define BRLAPI_HEADERSIZE sizeof(brlapi_header_t)
88 Size of packet headers
89 #define BRLAPI_MAXPACKETSIZE 512
91 Maximum packet size for packets exchanged on sockets and with braille
92 terminal
93 #define BRLAPI_PACKET_ACCEPTKEYRANGES 'u'
95 Unmask key ranges
96 #define BRLAPI_PACKET_ACK 'A'
98 Acknowledgement
99 #define BRLAPI_PACKET_AUTH 'a'
101 Authorization
102 #define BRLAPI_PACKET_ENTERRAWMODE '*'
104 Enter in raw mode
105 #define BRLAPI_PACKET_ENTERTTYMODE 't'
107 Asks for a specified tty
108 #define BRLAPI_PACKET_ERROR 'e'
110 non-fatal error
111 #define BRLAPI_PACKET_EXCEPTION 'E'
113 Exception
114 #define BRLAPI_PACKET_GETDISPLAYSIZE 's'
116 Dimensions of brl display
117 #define BRLAPI_PACKET_GETDRIVERNAME 'n'
119 Ask which driver is used
120 #define BRLAPI_PACKET_IGNOREKEYRANGES 'm'
122 Mask key ranges
123 #define BRLAPI_PACKET_KEY 'k'
125 Braille key
126 #define BRLAPI_PACKET_LEAVERAWMODE '#'
128 Leave raw mode
129 #define BRLAPI_PACKET_LEAVETTYMODE 'L'
131 Release the tty
132 #define BRLAPI_PACKET_PACKET 'p'
134 Raw packets
135 #define BRLAPI_PACKET_RESUMEDRIVER 'R'
137 Resume driver
138 #define BRLAPI_PACKET_SETFOCUS 'F'
140 Set current tty focus
141 #define BRLAPI_PACKET_SUSPENDDRIVER 'S'
143 Suspend driver
144 #define BRLAPI_PACKET_VERSION 'v'
146 Version
147 #define BRLAPI_PACKET_WRITE 'w'
149 Write
150 #define BRLAPI_PROTOCOL_VERSION ((uint32_t) 8)
152 #define BRLAPI_WF_ATTR_AND 0X08
153 And attributes
154 #define BRLAPI_WF_ATTR_OR 0X10
156 Or attributes
157 #define BRLAPI_WF_CHARSET 0X40
159 Charset
160 #define BRLAPI_WF_CURSOR 0X20
162 Cursor position
163 #define BRLAPI_WF_DISPLAYNUMBER 0X01
165 Flags for writing Display number
166 #define BRLAPI_WF_REGION 0X02
168 Region parameter
169 #define BRLAPI_WF_TEXT 0X04
171 Contains some text
172
174 ssize_t brlapi_readPacket (brlapi_fileDescriptor fd, brlapi_packetType_t *
175 type, void * buf, size_t size)
176 Read a packet from BrlAPI server
177 This function is for internal use, but one might use it if one really
179 knows what one is doing...
180 type is where the function will store the packet type; it should always
182 be one of the above defined BRLPACKET_* (or else something very nasty
183 must have happened :/).
184 The syntax is the same as read()'s.
186 Returns:
188 packet's size, -2 if EOF occurred, -1 on error or signal
189 interruption.
190 If the packet is larger than the supplied buffer, the buffer will be
192 filled with the beginning of the packet, the rest of the packet being
193 discarded. This follows the semantics of the recv system call when the
194 MSG_TRUNC option is given.
195 See also:
197 brlapi_writePacket()
198 ssize_t brlapi_readPacketContent (brlapi_fileDescriptor fd, size_t
200 packetSize, void * buf, size_t bufSize)
201 Read the content of a packet from BrlAPI server
202 This function is for internal use, but one might use it if one really
204 knows what one is doing...
205 packetSize is the size announced by brlapi_readPacketHeader()
207 bufSize is the size of buf
209 Returns:
211 packetSize, -2 if EOF occurred, -1 on error.
212 If the packet is larger than the supplied buffer, the buffer will be
214 filled with the beginning of the packet, the rest of the packet being
215 discarded. This follows the semantics of the recv system call when the
216 MSG_TRUNC option is given.
217 See also:
219 brlapi_writePacket() brlapi_readPacketHeader() brlapi_readPacket()
220 ssize_t brlapi_readPacketHeader (brlapi_fileDescriptor fd,
222 brlapi_packetType_t * packetType)
223 Read the header (type+size) of a packet from BrlAPI server
224 This function is for internal use, but one might use it if one really
226 knows what one is doing...
227 type is where the function will store the packet type; it should always
229 be one of the above defined BRLPACKET_* (or else something very nasty
230 must have happened :/).
231 Returns:
233 packet's size, -2 if EOF occurred, -1 on error or signal
234 interruption.
235 See also:
237 brlapi_writePacket() brlapi_readPacketContent brlapi_readPacket
238 ssize_t brlapi_writePacket (brlapi_fileDescriptor fd, brlapi_packetType_t
240 type, const void * buf, size_t size)
241 Send a packet to BrlAPI server
242 This function is for internal use, but one might use it if one really
244 knows what one is doing...
245 type should only be one of the above defined BRLPACKET_*.
247 The syntax is the same as write()'s.
249 Returns:
251 0 on success, -1 on failure.
252 See also:
254 brlapi_readPacketHeader() brlapi_readPacketContent()
255 brlapi_readPacket()
256
258 pthread_mutex_t brlapi_fd_mutex
259 Mutex for protecting concurrent fd access
260 In order to regulate concurrent access to the library's file descriptor
262 and requests to / answers from BrlAPI server, every function of the
263 library locks this mutex, namely
264 · brlapi_openConnection()
266 · brlapi_closeConnection()
268 · brlapi_enterRawMode()
270 · brlapi_leaveRawMode()
272 · brlapi_sendRaw()
274 · brlapi_recvRaw()
276 · brlapi_getDriverId()
278 · brlapi_getDriverName()
280 · brlapi_getDisplaySize()
282 · brlapi_enterTtyMode()
284 · brlapi_enterTtyModeWithPath()
286 · brlapi_leaveTtyMode()
288 · brlapi_*write*()
290 · brlapi_(un)?ignorekey(Range|Set)()
292 · brlapi_readKey()
294 If both these functions and brlapi_writePacket() or brlapi_readPacket()
296 are used in a multithreaded application, this mutex must be locked
297 before calling brlapi_writePacket() or brlapi_readPacket(), and
298 unlocked afterwards.
299Version 1.0 4 Jun 2007 BrlAPI's protocol(3)