brlapi_protocol - BrlAPI's protocol

Generated automatically by Doxygen for BrlAPI from the source code. BrlAPI Version 0.8 brlapi_protocol(3)

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.

ssize_tbrlapi_readPacket(brlapi_fileDescriptorfd,brlapi_packetType_t*type,void*buf,size_tsize) 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. Seealsobrlapi_writePacket()ssize_tbrlapi_readPacketContent(brlapi_fileDescriptorfd,size_tpacketSize,void*buf,size_tbufSize) 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 bufReturns 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. Seealsobrlapi_writePacket()brlapi_readPacketHeader()brlapi_readPacket()ssize_tbrlapi_readPacketHeader(brlapi_fileDescriptorfd,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. Seealsobrlapi_writePacket()brlapi_readPacketContentbrlapi_readPacketssize_tbrlapi_writePacket(brlapi_fileDescriptorfd,brlapi_packetType_ttype,constvoid*buf,size_tsize) 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. Seealsobrlapi_readPacketHeader()brlapi_readPacketContent()brlapi_readPacket()

#defineBRLAPI_AUTH_CRED'C' Explicit socket credentials authorization #defineBRLAPI_AUTH_KEY'K' Key authorization #defineBRLAPI_AUTH_NONE'N' No or implicit authorization #defineBRLAPI_DEVICE_MAGIC(0xdeadbeefL) Magic number to give when sending a BRLPACKET_ENTERRAWMODE or BRLPACKET_SUSPEND packet #defineBRLAPI_HEADERSIZEsizeof(brlapi_header_t) Size of packet headers #defineBRLAPI_MAXPACKETSIZE4096 Maximum packet size for packets exchanged on sockets and with braille terminal #defineBRLAPI_MAXPARAMSIZE(BRLAPI_MAXPACKETSIZE-(sizeof(uint32_t)+sizeof(brlapi_param_t)+2*sizeof(uint32_t)))#defineBRLAPI_PACKET_ACCEPTKEYRANGES'u' Unmask key ranges #defineBRLAPI_PACKET_ACK'A' Acknowledgement #defineBRLAPI_PACKET_AUTH'a' Authorization #defineBRLAPI_PACKET_ENTERRAWMODE'*' Enter in raw mode #defineBRLAPI_PACKET_ENTERTTYMODE't' Asks for a specified tty #defineBRLAPI_PACKET_ERROR'e' non-fatal error #defineBRLAPI_PACKET_EXCEPTION'E' Exception #defineBRLAPI_PACKET_GETDISPLAYSIZE's' Dimensions of brl display #defineBRLAPI_PACKET_GETDRIVERNAME'n' Ask which driver is used #defineBRLAPI_PACKET_GETMODELID'd' Ask which model is used #defineBRLAPI_PACKET_IGNOREKEYRANGES'm' Mask key ranges #defineBRLAPI_PACKET_KEY'k' Braille key #defineBRLAPI_PACKET_LEAVERAWMODE'#' Leave raw mode #defineBRLAPI_PACKET_LEAVETTYMODE'L' Release the tty #defineBRLAPI_PACKET_PACKET'p' Raw packets #defineBRLAPI_PACKET_PARAM_REQUEST(('P'<<8)+'R') Parameter request #defineBRLAPI_PACKET_PARAM_UPDATE(('P'<<8)+'U') Parameter update #defineBRLAPI_PACKET_PARAM_VALUE(('P'<<8)+'V') Parameter value #defineBRLAPI_PACKET_RESUMEDRIVER'R' Resume driver #defineBRLAPI_PACKET_SETFOCUS'F' Set current tty focus #defineBRLAPI_PACKET_SUSPENDDRIVER'S' Suspend driver #defineBRLAPI_PACKET_SYNCHRONIZE'Z' Synchronize exceptions #defineBRLAPI_PACKET_VERSION'v' Version #defineBRLAPI_PACKET_WRITE'w' Write #defineBRLAPI_PARAMF_GET0X100/**Getcurrentparametervalue*/ Flags for parameter requests #defineBRLAPI_PARAMF_SUBSCRIBE0X200/**Subscribetoparameterupdates*/#defineBRLAPI_PARAMF_UNSUBSCRIBE0X400/**Unsubscribefromparameterupdates*/#defineBRLAPI_PROTOCOL_VERSION((uint32_t)8)/**Communicationprotocolversion*/#defineBRLAPI_PVF_GLOBAL0X01/**Valueistheglobalvalue*/ Flags for parameter values #defineBRLAPI_WF_ATTR_AND0X08 And attributes #defineBRLAPI_WF_ATTR_OR0X10 Or attributes #defineBRLAPI_WF_CHARSET0X40 Charset #defineBRLAPI_WF_CURSOR0X20 Cursor position #defineBRLAPI_WF_DISPLAYNUMBER0X01 Flags for writing Display number #defineBRLAPI_WF_REGION0X02 Region parameter #defineBRLAPI_WF_TEXT0X04 Contains some text

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

DataStructures 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_tMacros #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

pthread_mutex_tbrlapi_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.