Go to main content

man pages section 3: Library Interfaces and Headers

Exit Print View

Updated: Wednesday, July 27, 2022
 
 

brlapi_writePacket (3)

Name

brlapi_writePacket - 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
union brlapi_packet_t

Macros
#define BRLAPI_PROTOCOL_VERSION   ((uint32_t) 8) /** Communication
protocol version */
#define BRLAPI_MAXPACKETSIZE   512
#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_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

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
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
uint32_t brlapi_packet_t::uint32
pthread_mutex_t brlapi_fd_mutex

Description

brlapi_protocol(3)                  BrlAPI                  brlapi_protocol(3)



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
       union brlapi_packet_t

   Macros
       #define BRLAPI_PROTOCOL_VERSION   ((uint32_t) 8) /** Communication
           protocol version */
       #define BRLAPI_MAXPACKETSIZE   512
       #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_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

   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
       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
       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   512
       Maximum packet size for packets exchanged on sockets and with braille
       terminal

   #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_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_PROTOCOL_VERSION   ((uint32_t) 8) /** Communication protocol
       version */
   #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 [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

       o brlapi_openConnection()

       o brlapi_closeConnection()

       o brlapi_enterRawMode()

       o brlapi_leaveRawMode()

       o brlapi_sendRaw()

       o brlapi_recvRaw()

       o brlapi_getDriverName()

       o brlapi_getDisplaySize()

       o brlapi_enterTtyMode()

       o brlapi_enterTtyModeWithPath()

       o brlapi_leaveTtyMode()

       o brlapi_*write*()

       o brlapi_(un)?ignorekey(Range|Set)()

       o 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_writeArgumentsPacket_t::data
       Flags to tell which fields are present

   unsigned char brlapi_packet_t::data[BRLAPI_MAXPACKETSIZE]
   brlapi_errorPacket_t brlapi_packet_t::error
   uint32_t brlapi_writeArgumentsPacket_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
   uint32_t brlapi_versionPacket_t::protocolVersion
   uint32_t brlapi_header_t::size
   brlapi_packetType_t brlapi_header_t::type
   uint32_t brlapi_authClientPacket_t::type
   uint32_t brlapi_authServerPacket_t::type[1]
   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.



ATTRIBUTES
       See attributes(7) for descriptions of the following attributes:


       +---------------+------------------------------+
       |ATTRIBUTE TYPE |       ATTRIBUTE VALUE        |
       +---------------+------------------------------+
       |Availability   | library/accessibility/brltty |
       +---------------+------------------------------+
       |Stability      | Pass-through volatile        |
       +---------------+------------------------------+

NOTES
       Source code for open source software components in Oracle Solaris can
       be found at https://www.oracle.com/downloads/opensource/solaris-source-
       code-downloads.html.

       This software was built from source available at
       https://github.com/oracle/solaris-userland.  The original community
       source was downloaded from
       http://mielke.cc/brltty//archive/brltty-6.0.tar.xz.

       Further information about this software can be found on the open source
       community website at http://mielke.cc/brltty/.



Version 0.7                     Mon Jun 27 2022             brlapi_protocol(3)