---
name: "brlapi_protocol"
section: "3"
platform: "linux"
package: "libbrlapi-dev"
version: "6.7-3.1+deb13u3"
release: "Debian 13 (Trixie)"
platforms: ["linux"]
url: "https://new.carta.tech/brlapi_protocol"
---

# brlapi\_protocol(3)

BrlAPI's protocol - Instructions and constants for BrlAPI 's protocol.

## NAME

brlapi\_protocol - BrlAPI's protocol

 \- Instructions and constants for *BrlAPI* 's protocol.

## SYNOPSIS

### Data Structures

struct **brlapi\_header\_t**\
 struct **brlapi\_versionPacket\_t**\
 struct **brlapi\_authClientPacket\_t**\
 struct **brlapi\_authServerPacket\_t**\
 struct **brlapi\_errorPacket\_t**\
 struct **brlapi\_getDriverSpecificModePacket\_t**\
 struct **brlapi\_writeArgumentsPacket\_t**\
 struct **brlapi\_paramValuePacket\_t**\
 struct **brlapi\_paramRequestPacket\_t**\
 union **brlapi\_packet\_t**\

### Macros

\#define **BRLAPI\_PROTOCOL\_VERSION**   ((uint32\_t) 8) /\*\* Communication protocol version \*/\
 \#define **BRLAPI\_MAXPACKETSIZE**   4096\
 \#define **BRLAPI\_PACKET\_VERSION**   'v'\
 \#define **BRLAPI\_PACKET\_AUTH**   'a'\
 \#define **BRLAPI\_PACKET\_GETDRIVERNAME**   'n'\
 \#define **BRLAPI\_PACKET\_GETMODELID**   'd'\
 \#define **BRLAPI\_PACKET\_GETDISPLAYSIZE**   's'\
 \#define **BRLAPI\_PACKET\_ENTERTTYMODE**   't'\
 \#define **BRLAPI\_PACKET\_SETFOCUS**   'F'\
 \#define **BRLAPI\_PACKET\_LEAVETTYMODE**   'L'\
 \#define **BRLAPI\_PACKET\_KEY**   'k'\
 \#define **BRLAPI\_PACKET\_IGNOREKEYRANGES**   'm'\
 \#define **BRLAPI\_PACKET\_ACCEPTKEYRANGES**   'u'\
 \#define **BRLAPI\_PACKET\_WRITE**   'w'\
 \#define **BRLAPI\_PACKET\_ENTERRAWMODE**   '\*'\
 \#define **BRLAPI\_PACKET\_LEAVERAWMODE**   '#'\
 \#define **BRLAPI\_PACKET\_PACKET**   'p'\
 \#define **BRLAPI\_PACKET\_ACK**   'A'\
 \#define **BRLAPI\_PACKET\_ERROR**   'e'\
 \#define **BRLAPI\_PACKET\_EXCEPTION**   'E'\
 \#define **BRLAPI\_PACKET\_SUSPENDDRIVER**   'S'\
 \#define **BRLAPI\_PACKET\_RESUMEDRIVER**   'R'\
 \#define **BRLAPI\_PACKET\_SYNCHRONIZE**   'Z'\
 \#define **BRLAPI\_PACKET\_PARAM\_VALUE**   (('P'\<\<8) + 'V')\
 \#define **BRLAPI\_PACKET\_PARAM\_REQUEST**   (('P'\<\<8) + 'R')\
 \#define **BRLAPI\_PACKET\_PARAM\_UPDATE**   (('P'\<\<8) + 'U')\
 \#define **BRLAPI\_DEVICE\_MAGIC**   (0xdeadbeefL)\
 \#define **BRLAPI\_HEADERSIZE**   sizeof(**brlapi\_header\_t**)\
 \#define **BRLAPI\_AUTH\_NONE**   'N'\
 \#define **BRLAPI\_AUTH\_KEY**   'K'\
 \#define **BRLAPI\_AUTH\_CRED**   'C'\
 \#define **BRLAPI\_WF\_DISPLAYNUMBER**   0X01\
 \#define **BRLAPI\_WF\_REGION**   0X02\
 \#define **BRLAPI\_WF\_TEXT**   0X04\
 \#define **BRLAPI\_WF\_ATTR\_AND**   0X08\
 \#define **BRLAPI\_WF\_ATTR\_OR**   0X10\
 \#define **BRLAPI\_WF\_CURSOR**   0X20\
 \#define **BRLAPI\_WF\_CHARSET**   0X40\
 \#define **BRLAPI\_PVF\_GLOBAL**   0X01    /\*\* Value is the global value \*/\
 \#define **BRLAPI\_MAXPARAMSIZE**   (**BRLAPI\_MAXPACKETSIZE** - (sizeof(uint32\_t) + sizeof(**brlapi\_param\_t**) + 2\*sizeof(uint32\_t)))\
 \#define **BRLAPI\_PARAMF\_GET**   0X100    /\*\* Get current parameter value    \*/\
 \#define **BRLAPI\_PARAMF\_SUBSCRIBE**   0X200    /\*\* Subscribe to parameter updates \*/\
 \#define **BRLAPI\_PARAMF\_UNSUBSCRIBE**   0X400    /\*\* Unsubscribe from parameter updates \*/\

### Functions

ssize\_t **brlapi\_writePacket** (**brlapi\_fileDescriptor** fd, **brlapi\_packetType\_t** type, const void \*buf, size\_t size)\
 ssize\_t **brlapi\_readPacketHeader** (**brlapi\_fileDescriptor** fd, **brlapi\_packetType\_t** \*packetType)\
 ssize\_t **brlapi\_readPacketContent** (**brlapi\_fileDescriptor** fd, size\_t packetSize, void \*buf, size\_t bufSize)\
 ssize\_t **brlapi\_readPacket** (**brlapi\_fileDescriptor** fd, **brlapi\_packetType\_t** \*type, void \*buf, size\_t size)\

### Variables

pthread\_mutex\_t **brlapi\_fd\_mutex**\

## Detailed Description

These are defines for the protocol between *BrlAPI* 's server and clients. Understanding is not needed to use the *BrlAPI* library, so reading this is not needed unless really wanting to connect to *BrlAPI* without *BrlAPI* 's library.

## Macro Definition Documentation

### #define BRLAPI\_AUTH\_CRED 'C'

Explicit socket credentials authorization

### #define BRLAPI\_AUTH\_KEY 'K'

Key authorization \

### #define BRLAPI\_AUTH\_NONE 'N'

No or implicit authorization \

### #define BRLAPI\_DEVICE\_MAGIC (0xdeadbeefL)

Magic number to give when sending a BRLPACKET\_ENTERRAWMODE or BRLPACKET\_SUSPEND packet

### #define BRLAPI\_HEADERSIZE sizeof(brlapi\_header\_t)

Size of packet headers

### #define BRLAPI\_MAXPACKETSIZE 4096

Maximum packet size for packets exchanged on sockets and with braille terminal

### #define BRLAPI\_MAXPARAMSIZE (BRLAPI\_MAXPACKETSIZE - (sizeof(uint32\_t) + sizeof(brlapi\_param\_t) + 2\*sizeof(uint32\_t)))

### #define BRLAPI\_PACKET\_ACCEPTKEYRANGES 'u'

Unmask key ranges \

### #define BRLAPI\_PACKET\_ACK 'A'

Acknowledgement \

### #define BRLAPI\_PACKET\_AUTH 'a'

Authorization \

### #define BRLAPI\_PACKET\_ENTERRAWMODE '\*'

Enter in raw mode \

### #define BRLAPI\_PACKET\_ENTERTTYMODE 't'

Asks for a specified tty \

### #define BRLAPI\_PACKET\_ERROR 'e'

non-fatal error \

### #define BRLAPI\_PACKET\_EXCEPTION 'E'

Exception \

### #define BRLAPI\_PACKET\_GETDISPLAYSIZE 's'

Dimensions of brl display \

### #define BRLAPI\_PACKET\_GETDRIVERNAME 'n'

Ask which driver is used \

### #define BRLAPI\_PACKET\_GETMODELID 'd'

Ask which model is used \

### #define BRLAPI\_PACKET\_IGNOREKEYRANGES 'm'

Mask key ranges \

### #define BRLAPI\_PACKET\_KEY 'k'

Braille key \

### #define BRLAPI\_PACKET\_LEAVERAWMODE '#'

Leave raw mode \

### #define BRLAPI\_PACKET\_LEAVETTYMODE 'L'

Release the tty \

### #define BRLAPI\_PACKET\_PACKET 'p'

Raw packets \

### #define BRLAPI\_PACKET\_PARAM\_REQUEST (('P'\<\<8) + 'R')

Parameter request

### #define BRLAPI\_PACKET\_PARAM\_UPDATE (('P'\<\<8) + 'U')

Parameter update

### #define BRLAPI\_PACKET\_PARAM\_VALUE (('P'\<\<8) + 'V')

Parameter value \

### #define BRLAPI\_PACKET\_RESUMEDRIVER 'R'

Resume driver \

### #define BRLAPI\_PACKET\_SETFOCUS 'F'

Set current tty focus \

### #define BRLAPI\_PACKET\_SUSPENDDRIVER 'S'

Suspend driver \

### #define BRLAPI\_PACKET\_SYNCHRONIZE 'Z'

Synchronize exceptions \

### #define BRLAPI\_PACKET\_VERSION 'v'

Version \

### #define BRLAPI\_PACKET\_WRITE 'w'

Write \

### #define BRLAPI\_PARAMF\_GET 0X100 /\*\* Get current parameter value \*/

Flags for parameter requests

### #define BRLAPI\_PARAMF\_SUBSCRIBE 0X200 /\*\* Subscribe to parameter updates \*/

### #define BRLAPI\_PARAMF\_UNSUBSCRIBE 0X400 /\*\* Unsubscribe from parameter updates \*/

### #define BRLAPI\_PROTOCOL\_VERSION ((uint32\_t) 8) /\*\* Communication protocol version \*/

### #define BRLAPI\_PVF\_GLOBAL 0X01 /\*\* Value is the global value \*/

Flags for parameter values

### #define BRLAPI\_WF\_ATTR\_AND 0X08

And attributes \

### #define BRLAPI\_WF\_ATTR\_OR 0X10

Or attributes \

### #define BRLAPI\_WF\_CHARSET 0X40

Charset \

### #define BRLAPI\_WF\_CURSOR 0X20

Cursor position \

### #define BRLAPI\_WF\_DISPLAYNUMBER 0X01

Flags for writing Display number \

### #define BRLAPI\_WF\_REGION 0X02

Region parameter \

### #define BRLAPI\_WF\_TEXT 0X04

Contains some text \

## Function Documentation

### ssize\_t brlapi\_readPacket (brlapi\_fileDescriptor fd, brlapi\_packetType\_t \* type, void \* buf, size\_t size)

Read a packet from *BrlAPI* server

This function is for internal use, but one might use it if one really knows what one is doing...

*type* is where the function will store the packet type; it should always be one of the above defined BRLPACKET\_\* (or else something very nasty must have happened :/).

The syntax is the same as read()'s.

**Returns**

packet's size, -2 if `EOF` occurred, -1 on error or signal interruption.

If the packet is larger than the supplied buffer, the buffer will be filled with the beginning of the packet, the rest of the packet being discarded. This follows the semantics of the recv system call when the MSG\_TRUNC option is given.

**See also**

**brlapi\_writePacket()**

### ssize\_t brlapi\_readPacketContent (brlapi\_fileDescriptor fd, size\_t packetSize, void \* buf, size\_t bufSize)

Read the content of a packet from *BrlAPI* server

This function is for internal use, but one might use it if one really knows what one is doing...

*packetSize* is the size announced by **brlapi\_readPacketHeader()**

*bufSize* **is the size of** *buf*

**Returns**

**packetSize, -2 if** `EOF` **occurred, -1 on error.**

**If the packet is larger than the supplied buffer, the buffer will be filled with the beginning of the packet, the rest of the packet being discarded. This follows the semantics of the recv system call when the MSG\_TRUNC option is given.**

**See also**

**brlapi\_writePacket() brlapi\_readPacketHeader() brlapi\_readPacket()**

### ssize\_t brlapi\_readPacketHeader (brlapi\_fileDescriptor fd, brlapi\_packetType\_t \* packetType)

**Read the header (type+size) of a packet from** *BrlAPI* **server**

**This function is for internal use, but one might use it if one really knows what one is doing...**

*type* **is where the function will store the packet type; it should always be one of the above defined BRLPACKET\_\* (or else something very nasty must have happened :/).**

**Returns**

**packet's size, -2 if** `EOF` **occurred, -1 on error or signal interruption.**

**See also**

**brlapi\_writePacket() brlapi\_readPacketContent brlapi\_readPacket**

### ssize\_t brlapi\_writePacket (brlapi\_fileDescriptor fd, brlapi\_packetType\_t type, const void \* buf, size\_t size)

**Send a packet to** *BrlAPI* **server**

**This function is for internal use, but one might use it if one really knows what one is doing...**

*type* **should only be one of the above defined BRLPACKET\_\*.**

**The syntax is the same as write()'s.**

**Returns**

**0 on success, -1 on failure.**

**See also**

**brlapi\_readPacketHeader() brlapi\_readPacketContent() brlapi\_readPacket()**

## Variable Documentation

### pthread\_mutex\_t brlapi\_fd\_mutex` [extern]`

**Mutex for protecting concurrent fd access**

**In order to regulate concurrent access to the library's file descriptor and requests to / answers from** *BrlAPI* **server, every function of the library locks this mutex, namely**

- •

  **brlapi\_openConnection()**

- •

  **brlapi\_closeConnection()**

- •

  **brlapi\_enterRawMode()**

- •

  **brlapi\_leaveRawMode()**

- •

  **brlapi\_sendRaw()**

- •

  **brlapi\_recvRaw()**

- •

  **brlapi\_getDriverName()**

- •

  **brlapi\_getDisplaySize()**

- •

  **brlapi\_enterTtyMode()**

- •

  **brlapi\_enterTtyModeWithPath()**

- •

  **brlapi\_leaveTtyMode()**

- •

  **brlapi\_\*write\*()**

- •

  **brlapi\_(un)?ignorekey(Range\|Set)()**

- •

  **brlapi\_readKey()**

**If both these functions and brlapi\_writePacket() or brlapi\_readPacket() are used in a multithreaded application, this mutex must be locked before calling brlapi\_writePacket() or brlapi\_readPacket(), and unlocked afterwards.**

## Author

**Generated automatically by Doxygen for BrlAPI from the source code.**