/* * libbrlapi - A library providing access to braille terminals for applications. * * Copyright (C) 2002-2020 by * Samuel Thibault * Sébastien Hinderer * * libbrlapi comes with ABSOLUTELY NO WARRANTY. * * This is free software, placed under the terms of the * GNU Lesser General Public License, as published by the Free Software * Foundation; either version 2.1 of the License, or (at your option) any * later version. Please see the file LICENSE-LGPL for details. * * Web Page: http://brltty.app/ * * This software is maintained by Dave Mielke . */ /** \file * \brief types and constants for \e BrlAPI's protocol */ #ifndef BRLAPI_INCLUDED_PROTOCOL #define BRLAPI_INCLUDED_PROTOCOL #ifdef __cplusplus extern "C" { #endif /* __cplusplus */ #include "brlapi.h" /* this is for UINT32_MAX */ #include #ifndef UINT32_MAX #define UINT32_MAX (4294967295U) #endif /* UINT32_MAX */ /* The type size_t is defined there! */ #include /** \defgroup brlapi_protocol BrlAPI's protocol * \brief Instructions and constants for \e BrlAPI 's protocol * * These are defines for the protocol between \e BrlAPI 's server and clients. * Understanding is not needed to use the \e BrlAPI library, so reading this * is not needed unless really wanting to connect to \e BrlAPI without * \e BrlAPI 's library. * * @{ */ #define BRLAPI_PROTOCOL_VERSION ((uint32_t) 8) /** Communication protocol version */ /** Maximum packet size for packets exchanged on sockets and with braille * terminal */ #define BRLAPI_MAXPACKETSIZE 4096 #define BRLAPI_PACKET_VERSION 'v' /**< Version */ #define BRLAPI_PACKET_AUTH 'a' /**< Authorization */ #define BRLAPI_PACKET_GETDRIVERNAME 'n' /**< Ask which driver is used */ #define BRLAPI_PACKET_GETMODELID 'd' /**< Ask which model is used */ #define BRLAPI_PACKET_GETDISPLAYSIZE 's' /**< Dimensions of brl display */ #define BRLAPI_PACKET_ENTERTTYMODE 't' /**< Asks for a specified tty */ #define BRLAPI_PACKET_SETFOCUS 'F' /**< Set current tty focus */ #define BRLAPI_PACKET_LEAVETTYMODE 'L' /**< Release the tty */ #define BRLAPI_PACKET_KEY 'k' /**< Braille key */ #define BRLAPI_PACKET_IGNOREKEYRANGES 'm' /**< Mask key ranges */ #define BRLAPI_PACKET_ACCEPTKEYRANGES 'u' /**< Unmask key ranges */ #define BRLAPI_PACKET_WRITE 'w' /**< Write */ #define BRLAPI_PACKET_ENTERRAWMODE '*' /**< Enter in raw mode */ #define BRLAPI_PACKET_LEAVERAWMODE '#' /**< Leave raw mode */ #define BRLAPI_PACKET_PACKET 'p' /**< Raw packets */ #define BRLAPI_PACKET_ACK 'A' /**< Acknowledgement */ #define BRLAPI_PACKET_ERROR 'e' /**< non-fatal error */ #define BRLAPI_PACKET_EXCEPTION 'E' /**< Exception */ #define BRLAPI_PACKET_SUSPENDDRIVER 'S' /**< Suspend driver */ #define BRLAPI_PACKET_RESUMEDRIVER 'R' /**< Resume driver */ #define BRLAPI_PACKET_PARAM_VALUE (('P'<<8) + 'V') /**< Parameter value */ #define BRLAPI_PACKET_PARAM_REQUEST (('P'<<8) + 'R') /**< Parameter request*/ #define BRLAPI_PACKET_PARAM_UPDATE (('P'<<8) + 'U') /**< Parameter update */ /** Magic number to give when sending a BRLPACKET_ENTERRAWMODE or BRLPACKET_SUSPEND packet */ #define BRLAPI_DEVICE_MAGIC (0xdeadbeefL) /** Structure of packets headers */ typedef struct { uint32_t size; brlapi_packetType_t type; } brlapi_header_t; /** Size of packet headers */ #define BRLAPI_HEADERSIZE sizeof(brlapi_header_t) /** Structure of version packets */ typedef struct { uint32_t protocolVersion; } brlapi_versionPacket_t; /** Structure of authorization packets */ typedef struct { uint32_t type; unsigned char key; } brlapi_authClientPacket_t; typedef struct { uint32_t type[1]; } brlapi_authServerPacket_t; #define BRLAPI_AUTH_NONE 'N' /**< No or implicit authorization */ #define BRLAPI_AUTH_KEY 'K' /**< Key authorization */ #define BRLAPI_AUTH_CRED 'C' /**< Explicit socket credentials authorization */ /** Structure of error packets */ typedef struct { uint32_t code; brlapi_packetType_t type; unsigned char packet; } brlapi_errorPacket_t; /** Structure of enterRawMode / suspend packets */ typedef struct { uint32_t magic; unsigned char nameLength; char name; } brlapi_getDriverSpecificModePacket_t; /** Flags for writing */ #define BRLAPI_WF_DISPLAYNUMBER 0X01 /**< Display number */ #define BRLAPI_WF_REGION 0X02 /**< Region parameter */ #define BRLAPI_WF_TEXT 0X04 /**< Contains some text */ #define BRLAPI_WF_ATTR_AND 0X08 /**< And attributes */ #define BRLAPI_WF_ATTR_OR 0X10 /**< Or attributes */ #define BRLAPI_WF_CURSOR 0X20 /**< Cursor position */ #define BRLAPI_WF_CHARSET 0X40 /**< Charset */ /** Structure of extended write packets */ typedef struct { uint32_t flags; /** Flags to tell which fields are present */ unsigned char data; /** Fields in the same order as flag weight */ } brlapi_writeArgumentsPacket_t; /** Flags for parameter values */ #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))) /** Structure of Parameter value or update */ typedef struct { uint32_t flags; /** Flags to tell how value was gotten */ brlapi_param_t param; /** Which parameter being transmitted */ uint32_t subparam_hi; /** Which sub-parameter being transmitted, hi 32bits */ uint32_t subparam_lo; /** Which sub-parameter being transmitted, lo 32bits */ unsigned char data[BRLAPI_MAXPARAMSIZE]; /** Content of the parameter */ } brlapi_paramValuePacket_t; /** Flags for parameter requests */ #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 */ /** Structure of Parameter request */ typedef struct { uint32_t flags; /** Flags to tell whether/how to get values */ brlapi_param_t param; /** Which parameter to be transmitted */ uint32_t subparam_hi; /** Which sub-parameter being transmitted, hi 32bits */ uint32_t subparam_lo; /** Which sub-parameter being transmitted, lo 32bits */ } brlapi_paramRequestPacket_t; /** Type for packets. Should be used instead of a mere char[], since it has * correct alignment requirements. */ typedef union { unsigned char data[BRLAPI_MAXPACKETSIZE]; brlapi_versionPacket_t version; brlapi_authClientPacket_t authClient; brlapi_authServerPacket_t authServer; brlapi_errorPacket_t error; brlapi_getDriverSpecificModePacket_t getDriverSpecificMode; brlapi_writeArgumentsPacket_t writeArguments; brlapi_paramValuePacket_t paramValue; brlapi_paramRequestPacket_t paramRequest; uint32_t uint32; } brlapi_packet_t; /* brlapi_writePacket */ /** Send a packet to \e BrlAPI server * * This function is for internal use, but one might use it if one really knows * what one is doing... * * \e type should only be one of the above defined BRLPACKET_*. * * The syntax is the same as write()'s. * * \return 0 on success, -1 on failure. * * \sa brlapi_readPacketHeader() * brlapi_readPacketContent() * brlapi_readPacket() */ ssize_t brlapi_writePacket(brlapi_fileDescriptor fd, brlapi_packetType_t type, const void *buf, size_t size); /* brlapi_readPacketHeader */ /** Read the header (type+size) of a packet from \e BrlAPI server * * This function is for internal use, but one might use it if one really knows * what one is doing... * * \e 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 :/). * * \return packet's size, -2 if \c EOF occurred, -1 on error or signal * interruption. * * \sa brlapi_writePacket() * brlapi_readPacketContent * brlapi_readPacket */ ssize_t brlapi_readPacketHeader(brlapi_fileDescriptor fd, brlapi_packetType_t *packetType); /* brlapi_readPacketContent */ /** Read the content of a packet from \e BrlAPI server * * This function is for internal use, but one might use it if one really knows * what one is doing... * * \e packetSize is the size announced by \e brlapi_readPacketHeader() * * \e bufSize is the size of \e buf * * \return packetSize, -2 if \c 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. * * \sa brlapi_writePacket() * brlapi_readPacketHeader() * brlapi_readPacket() */ ssize_t brlapi_readPacketContent(brlapi_fileDescriptor fd, size_t packetSize, void *buf, size_t bufSize); /* brlapi_readPacket */ /** Read a packet from \e BrlAPI server * * This function is for internal use, but one might use it if one really knows * what one is doing... * * \e 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. * * \return packet's size, -2 if \c 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. * * \sa brlapi_writePacket() */ ssize_t brlapi_readPacket(brlapi_fileDescriptor fd, brlapi_packetType_t *type, void *buf, size_t size); /* 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 \e 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. */ #ifdef __MINGW32__ #include extern HANDLE brlapi_fd_mutex; #else /* __MINGW32__ */ #include extern pthread_mutex_t brlapi_fd_mutex; #endif /* __MINGW32__ */ /* @} */ #ifdef __cplusplus } #endif /* __cplusplus */ #endif /* BRLAPI_INCLUDED_PROTOCOL */