brlapi_protocol(3)

NAME
brlapi_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_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
uint32_t brlapi_header_t::size
brlapi_packetType_t brlapi_header_t::type
uint32_t brlapi_versionPacket_t::protocolVersion
uint32_t brlapi_authClientPacket_t::type
unsigned char brlapi_authClientPacket_t::key
uint32_t brlapi_authServerPacket_t::type [1]
uint32_t brlapi_errorPacket_t::code
brlapi_packetType_t brlapi_errorPacket_t::type
unsigned char brlapi_errorPacket_t::packet
uint32_t brlapi_getDriverSpecificModePacket_t::magic
unsigned char brlapi_getDriverSpecificModePacket_t::nameLength
char brlapi_getDriverSpecificModePacket_t::name
uint32_t brlapi_writeArgumentsPacket_t::flags
unsigned char brlapi_writeArgumentsPacket_t::data
uint32_t brlapi_paramValuePacket_t::flags
brlapi_param_t brlapi_paramValuePacket_t::param
uint32_t brlapi_paramValuePacket_t::subparam_hi
uint32_t brlapi_paramValuePacket_t::subparam_lo
unsigned char brlapi_paramValuePacket_t::data [BRLAPI_MAXPARAMSIZE]
uint32_t brlapi_paramRequestPacket_t::flags
brlapi_param_t brlapi_paramRequestPacket_t::param
uint32_t brlapi_paramRequestPacket_t::subparam_hi
uint32_t brlapi_paramRequestPacket_t::subparam_lo
unsigned char brlapi_packet_t::data [BRLAPI_MAXPACKETSIZE]
brlapi_versionPacket_t brlapi_packet_t::version
brlapi_authClientPacket_t brlapi_packet_t::authClient
brlapi_authServerPacket_t brlapi_packet_t::authServer
brlapi_errorPacket_t brlapi_packet_t::error
brlapi_getDriverSpecificModePacket_t brlapi_packet_t::getDriverSpecificMode
brlapi_writeArgumentsPacket_t brlapi_packet_t::writeArguments
brlapi_paramValuePacket_t brlapi_packet_t::paramValue
brlapi_paramRequestPacket_t brlapi_packet_t::paramRequest
uint32_t brlapi_packet_t::uint32
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_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

  brlapi_authClientPacket_t brlapi_packet_t::authClient

  brlapi_authServerPacket_t brlapi_packet_t::authServer

  pthread_mutex_t brlapi_fd_mutex
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.

  uint32_t brlapi_errorPacket_t::code

  unsigned char brlapi_packet_t::data[BRLAPI_MAXPACKETSIZE]

  unsigned char brlapi_paramValuePacket_t::data[BRLAPI_MAXPARAMSIZE]
Which sub-parameter being transmitted, lo 32bits

  unsigned char brlapi_writeArgumentsPacket_t::data
Flags to tell which fields are present

  brlapi_errorPacket_t brlapi_packet_t::error

  uint32_t brlapi_writeArgumentsPacket_t::flags

  uint32_t brlapi_paramValuePacket_t::flags

  uint32_t brlapi_paramRequestPacket_t::flags

  brlapi_getDriverSpecificModePacket_t brlapi_packet_t::getDriverSpecificMode

  unsigned char brlapi_authClientPacket_t::key

  uint32_t brlapi_getDriverSpecificModePacket_t::magic

  char brlapi_getDriverSpecificModePacket_t::name

  unsigned char brlapi_getDriverSpecificModePacket_t::nameLength

  unsigned char brlapi_errorPacket_t::packet

  brlapi_param_t brlapi_paramValuePacket_t::param
Flags to tell how value was gotten

  brlapi_param_t brlapi_paramRequestPacket_t::param
Flags to tell whether/how to get values

  brlapi_paramRequestPacket_t brlapi_packet_t::paramRequest

  brlapi_paramValuePacket_t brlapi_packet_t::paramValue

  uint32_t brlapi_versionPacket_t::protocolVersion

  uint32_t brlapi_header_t::size

  uint32_t brlapi_paramValuePacket_t::subparam_hi
Which parameter being transmitted

  uint32_t brlapi_paramRequestPacket_t::subparam_hi
Which parameter to be transmitted

  uint32_t brlapi_paramValuePacket_t::subparam_lo
Which sub-parameter being transmitted, hi 32bits

  uint32_t brlapi_paramRequestPacket_t::subparam_lo
Which sub-parameter being transmitted, hi 32bits

  uint32_t brlapi_authServerPacket_t::type[1]

  brlapi_packetType_t brlapi_header_t::type

  uint32_t brlapi_authClientPacket_t::type

  brlapi_packetType_t brlapi_errorPacket_t::type

  uint32_t brlapi_packet_t::uint32

  brlapi_versionPacket_t brlapi_packet_t::version

  brlapi_writeArgumentsPacket_t brlapi_packet_t::writeArguments

Author

Generated automatically by Doxygen for BrlAPI from the source code.