.TH "brlapi_protocol" 3 "Version 0.8" "BrlAPI" \" -*- nroff -*- .ad l .nh .SH NAME brlapi_protocol \- BrlAPI's protocol .PP \- Instructions and constants for \fIBrlAPI\fP 's protocol\&. .SH SYNOPSIS .br .PP .SS "Data Structures" .in +1c .ti -1c .RI "struct \fBbrlapi_header_t\fP" .br .ti -1c .RI "struct \fBbrlapi_versionPacket_t\fP" .br .ti -1c .RI "struct \fBbrlapi_authClientPacket_t\fP" .br .ti -1c .RI "struct \fBbrlapi_authServerPacket_t\fP" .br .ti -1c .RI "struct \fBbrlapi_errorPacket_t\fP" .br .ti -1c .RI "struct \fBbrlapi_getDriverSpecificModePacket_t\fP" .br .ti -1c .RI "struct \fBbrlapi_writeArgumentsPacket_t\fP" .br .ti -1c .RI "struct \fBbrlapi_paramValuePacket_t\fP" .br .ti -1c .RI "struct \fBbrlapi_paramRequestPacket_t\fP" .br .ti -1c .RI "union \fBbrlapi_packet_t\fP" .br .in -1c .SS "Macros" .in +1c .ti -1c .RI "#define \fBBRLAPI_PROTOCOL_VERSION\fP ((uint32_t) 8) /** Communication protocol version */" .br .ti -1c .RI "#define \fBBRLAPI_MAXPACKETSIZE\fP 4096" .br .ti -1c .RI "#define \fBBRLAPI_PACKET_VERSION\fP 'v'" .br .ti -1c .RI "#define \fBBRLAPI_PACKET_AUTH\fP 'a'" .br .ti -1c .RI "#define \fBBRLAPI_PACKET_GETDRIVERNAME\fP 'n'" .br .ti -1c .RI "#define \fBBRLAPI_PACKET_GETMODELID\fP 'd'" .br .ti -1c .RI "#define \fBBRLAPI_PACKET_GETDISPLAYSIZE\fP 's'" .br .ti -1c .RI "#define \fBBRLAPI_PACKET_ENTERTTYMODE\fP 't'" .br .ti -1c .RI "#define \fBBRLAPI_PACKET_SETFOCUS\fP 'F'" .br .ti -1c .RI "#define \fBBRLAPI_PACKET_LEAVETTYMODE\fP 'L'" .br .ti -1c .RI "#define \fBBRLAPI_PACKET_KEY\fP 'k'" .br .ti -1c .RI "#define \fBBRLAPI_PACKET_IGNOREKEYRANGES\fP 'm'" .br .ti -1c .RI "#define \fBBRLAPI_PACKET_ACCEPTKEYRANGES\fP 'u'" .br .ti -1c .RI "#define \fBBRLAPI_PACKET_WRITE\fP 'w'" .br .ti -1c .RI "#define \fBBRLAPI_PACKET_ENTERRAWMODE\fP '*'" .br .ti -1c .RI "#define \fBBRLAPI_PACKET_LEAVERAWMODE\fP '#'" .br .ti -1c .RI "#define \fBBRLAPI_PACKET_PACKET\fP 'p'" .br .ti -1c .RI "#define \fBBRLAPI_PACKET_ACK\fP 'A'" .br .ti -1c .RI "#define \fBBRLAPI_PACKET_ERROR\fP 'e'" .br .ti -1c .RI "#define \fBBRLAPI_PACKET_EXCEPTION\fP 'E'" .br .ti -1c .RI "#define \fBBRLAPI_PACKET_SUSPENDDRIVER\fP 'S'" .br .ti -1c .RI "#define \fBBRLAPI_PACKET_RESUMEDRIVER\fP 'R'" .br .ti -1c .RI "#define \fBBRLAPI_PACKET_SYNCHRONIZE\fP 'Z'" .br .ti -1c .RI "#define \fBBRLAPI_PACKET_PARAM_VALUE\fP (('P'<<8) + 'V')" .br .ti -1c .RI "#define \fBBRLAPI_PACKET_PARAM_REQUEST\fP (('P'<<8) + 'R')" .br .ti -1c .RI "#define \fBBRLAPI_PACKET_PARAM_UPDATE\fP (('P'<<8) + 'U')" .br .ti -1c .RI "#define \fBBRLAPI_DEVICE_MAGIC\fP (0xdeadbeefL)" .br .ti -1c .RI "#define \fBBRLAPI_HEADERSIZE\fP sizeof(\fBbrlapi_header_t\fP)" .br .ti -1c .RI "#define \fBBRLAPI_AUTH_NONE\fP 'N'" .br .ti -1c .RI "#define \fBBRLAPI_AUTH_KEY\fP 'K'" .br .ti -1c .RI "#define \fBBRLAPI_AUTH_CRED\fP 'C'" .br .ti -1c .RI "#define \fBBRLAPI_WF_DISPLAYNUMBER\fP 0X01" .br .ti -1c .RI "#define \fBBRLAPI_WF_REGION\fP 0X02" .br .ti -1c .RI "#define \fBBRLAPI_WF_TEXT\fP 0X04" .br .ti -1c .RI "#define \fBBRLAPI_WF_ATTR_AND\fP 0X08" .br .ti -1c .RI "#define \fBBRLAPI_WF_ATTR_OR\fP 0X10" .br .ti -1c .RI "#define \fBBRLAPI_WF_CURSOR\fP 0X20" .br .ti -1c .RI "#define \fBBRLAPI_WF_CHARSET\fP 0X40" .br .ti -1c .RI "#define \fBBRLAPI_PVF_GLOBAL\fP 0X01 /** Value is the global value */" .br .ti -1c .RI "#define \fBBRLAPI_MAXPARAMSIZE\fP (\fBBRLAPI_MAXPACKETSIZE\fP \- (sizeof(uint32_t) + sizeof(\fBbrlapi_param_t\fP) + 2*sizeof(uint32_t)))" .br .ti -1c .RI "#define \fBBRLAPI_PARAMF_GET\fP 0X100 /** Get current parameter value */" .br .ti -1c .RI "#define \fBBRLAPI_PARAMF_SUBSCRIBE\fP 0X200 /** Subscribe to parameter updates */" .br .ti -1c .RI "#define \fBBRLAPI_PARAMF_UNSUBSCRIBE\fP 0X400 /** Unsubscribe from parameter updates */" .br .in -1c .SS "Functions" .in +1c .ti -1c .RI "ssize_t \fBbrlapi_writePacket\fP (\fBbrlapi_fileDescriptor\fP fd, \fBbrlapi_packetType_t\fP type, const void *buf, size_t size)" .br .ti -1c .RI "ssize_t \fBbrlapi_readPacketHeader\fP (\fBbrlapi_fileDescriptor\fP fd, \fBbrlapi_packetType_t\fP *packetType)" .br .ti -1c .RI "ssize_t \fBbrlapi_readPacketContent\fP (\fBbrlapi_fileDescriptor\fP fd, size_t packetSize, void *buf, size_t bufSize)" .br .ti -1c .RI "ssize_t \fBbrlapi_readPacket\fP (\fBbrlapi_fileDescriptor\fP fd, \fBbrlapi_packetType_t\fP *type, void *buf, size_t size)" .br .in -1c .SS "Variables" .in +1c .ti -1c .RI "pthread_mutex_t \fBbrlapi_fd_mutex\fP" .br .in -1c .SH "Detailed Description" .PP These are defines for the protocol between \fIBrlAPI\fP 's server and clients\&. Understanding is not needed to use the \fIBrlAPI\fP library, so reading this is not needed unless really wanting to connect to \fIBrlAPI\fP without \fIBrlAPI\fP 's library\&. .SH "Macro Definition Documentation" .PP .SS "#define BRLAPI_AUTH_CRED 'C'" Explicit socket credentials authorization .SS "#define BRLAPI_AUTH_KEY 'K'" Key authorization .br .SS "#define BRLAPI_AUTH_NONE 'N'" No or implicit authorization .br .SS "#define BRLAPI_DEVICE_MAGIC (0xdeadbeefL)" Magic number to give when sending a BRLPACKET_ENTERRAWMODE or BRLPACKET_SUSPEND packet .SS "#define BRLAPI_HEADERSIZE sizeof(\fBbrlapi_header_t\fP)" Size of packet headers .SS "#define BRLAPI_MAXPACKETSIZE 4096" Maximum packet size for packets exchanged on sockets and with braille terminal .SS "#define BRLAPI_MAXPARAMSIZE (\fBBRLAPI_MAXPACKETSIZE\fP \- (sizeof(uint32_t) + sizeof(\fBbrlapi_param_t\fP) + 2*sizeof(uint32_t)))" .SS "#define BRLAPI_PACKET_ACCEPTKEYRANGES 'u'" Unmask key ranges .br .SS "#define BRLAPI_PACKET_ACK 'A'" Acknowledgement .br .SS "#define BRLAPI_PACKET_AUTH 'a'" Authorization .br .SS "#define BRLAPI_PACKET_ENTERRAWMODE '*'" Enter in raw mode .br .SS "#define BRLAPI_PACKET_ENTERTTYMODE 't'" Asks for a specified tty .br .SS "#define BRLAPI_PACKET_ERROR 'e'" non-fatal error .br .SS "#define BRLAPI_PACKET_EXCEPTION 'E'" Exception .br .SS "#define BRLAPI_PACKET_GETDISPLAYSIZE 's'" Dimensions of brl display .br .SS "#define BRLAPI_PACKET_GETDRIVERNAME 'n'" Ask which driver is used .br .SS "#define BRLAPI_PACKET_GETMODELID 'd'" Ask which model is used .br .SS "#define BRLAPI_PACKET_IGNOREKEYRANGES 'm'" Mask key ranges .br .SS "#define BRLAPI_PACKET_KEY 'k'" Braille key .br .SS "#define BRLAPI_PACKET_LEAVERAWMODE '#'" Leave raw mode .br .SS "#define BRLAPI_PACKET_LEAVETTYMODE 'L'" Release the tty .br .SS "#define BRLAPI_PACKET_PACKET 'p'" Raw packets .br .SS "#define BRLAPI_PACKET_PARAM_REQUEST (('P'<<8) + 'R')" Parameter request .SS "#define BRLAPI_PACKET_PARAM_UPDATE (('P'<<8) + 'U')" Parameter update .SS "#define BRLAPI_PACKET_PARAM_VALUE (('P'<<8) + 'V')" Parameter value .br .SS "#define BRLAPI_PACKET_RESUMEDRIVER 'R'" Resume driver .br .SS "#define BRLAPI_PACKET_SETFOCUS 'F'" Set current tty focus .br .SS "#define BRLAPI_PACKET_SUSPENDDRIVER 'S'" Suspend driver .br .SS "#define BRLAPI_PACKET_SYNCHRONIZE 'Z'" Synchronize exceptions .br .SS "#define BRLAPI_PACKET_VERSION 'v'" Version .br .SS "#define BRLAPI_PACKET_WRITE 'w'" Write .br .SS "#define BRLAPI_PARAMF_GET 0X100 /** Get current parameter value */" Flags for parameter requests .SS "#define BRLAPI_PARAMF_SUBSCRIBE 0X200 /** Subscribe to parameter updates */" .SS "#define BRLAPI_PARAMF_UNSUBSCRIBE 0X400 /** Unsubscribe from parameter updates */" .SS "#define BRLAPI_PROTOCOL_VERSION ((uint32_t) 8) /** Communication protocol version */" .SS "#define BRLAPI_PVF_GLOBAL 0X01 /** Value is the global value */" Flags for parameter values .SS "#define BRLAPI_WF_ATTR_AND 0X08" And attributes .br .SS "#define BRLAPI_WF_ATTR_OR 0X10" Or attributes .br .SS "#define BRLAPI_WF_CHARSET 0X40" Charset .br .SS "#define BRLAPI_WF_CURSOR 0X20" Cursor position .br .SS "#define BRLAPI_WF_DISPLAYNUMBER 0X01" Flags for writing Display number .br .SS "#define BRLAPI_WF_REGION 0X02" Region parameter .br .SS "#define BRLAPI_WF_TEXT 0X04" Contains some text .br .SH "Function Documentation" .PP .SS "ssize_t brlapi_readPacket (\fBbrlapi_fileDescriptor\fP fd, \fBbrlapi_packetType_t\fP * type, void * buf, size_t size)" Read a packet from \fIBrlAPI\fP server .PP This function is for internal use, but one might use it if one really knows what one is doing\&.\&.\&. .PP \fItype\fP 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 :/)\&. .PP The syntax is the same as read()'s\&. .PP \fBReturns\fP .RS 4 packet's size, -2 if \fCEOF\fP occurred, -1 on error or signal interruption\&. .RE .PP 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\&. .PP \fBSee also\fP .RS 4 \fBbrlapi_writePacket()\fP .RE .PP .SS "ssize_t brlapi_readPacketContent (\fBbrlapi_fileDescriptor\fP fd, size_t packetSize, void * buf, size_t bufSize)" Read the content of a packet from \fIBrlAPI\fP server .PP This function is for internal use, but one might use it if one really knows what one is doing\&.\&.\&. .PP \fIpacketSize\fP is the size announced by \fI\fBbrlapi_readPacketHeader()\fP\fP .PP \fIbufSize\fP is the size of \fIbuf\fP .PP \fBReturns\fP .RS 4 packetSize, -2 if \fCEOF\fP occurred, -1 on error\&. .RE .PP 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\&. .PP \fBSee also\fP .RS 4 \fBbrlapi_writePacket()\fP \fBbrlapi_readPacketHeader()\fP \fBbrlapi_readPacket()\fP .RE .PP .SS "ssize_t brlapi_readPacketHeader (\fBbrlapi_fileDescriptor\fP fd, \fBbrlapi_packetType_t\fP * packetType)" Read the header (type+size) of a packet from \fIBrlAPI\fP server .PP This function is for internal use, but one might use it if one really knows what one is doing\&.\&.\&. .PP \fItype\fP 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 :/)\&. .PP \fBReturns\fP .RS 4 packet's size, -2 if \fCEOF\fP occurred, -1 on error or signal interruption\&. .RE .PP \fBSee also\fP .RS 4 \fBbrlapi_writePacket()\fP \fBbrlapi_readPacketContent\fP \fBbrlapi_readPacket\fP .RE .PP .SS "ssize_t brlapi_writePacket (\fBbrlapi_fileDescriptor\fP fd, \fBbrlapi_packetType_t\fP type, const void * buf, size_t size)" Send a packet to \fIBrlAPI\fP server .PP This function is for internal use, but one might use it if one really knows what one is doing\&.\&.\&. .PP \fItype\fP should only be one of the above defined BRLPACKET_*\&. .PP The syntax is the same as write()'s\&. .PP \fBReturns\fP .RS 4 0 on success, -1 on failure\&. .RE .PP \fBSee also\fP .RS 4 \fBbrlapi_readPacketHeader()\fP \fBbrlapi_readPacketContent()\fP \fBbrlapi_readPacket()\fP .RE .PP .SH "Variable Documentation" .PP .SS "pthread_mutex_t brlapi_fd_mutex\fC [extern]\fP" Mutex for protecting concurrent fd access .PP In order to regulate concurrent access to the library's file descriptor and requests to / answers from \fIBrlAPI\fP server, every function of the library locks this mutex, namely .PP .IP "\(bu" 2 \fBbrlapi_openConnection()\fP .IP "\(bu" 2 \fBbrlapi_closeConnection()\fP .IP "\(bu" 2 \fBbrlapi_enterRawMode()\fP .IP "\(bu" 2 \fBbrlapi_leaveRawMode()\fP .IP "\(bu" 2 \fBbrlapi_sendRaw()\fP .IP "\(bu" 2 \fBbrlapi_recvRaw()\fP .IP "\(bu" 2 \fBbrlapi_getDriverName()\fP .IP "\(bu" 2 \fBbrlapi_getDisplaySize()\fP .IP "\(bu" 2 \fBbrlapi_enterTtyMode()\fP .IP "\(bu" 2 \fBbrlapi_enterTtyModeWithPath()\fP .IP "\(bu" 2 \fBbrlapi_leaveTtyMode()\fP .IP "\(bu" 2 brlapi_*write*() .IP "\(bu" 2 brlapi_(un)?ignorekey(Range|Set)() .IP "\(bu" 2 \fBbrlapi_readKey()\fP .PP .PP If both these functions and \fBbrlapi_writePacket()\fP or \fBbrlapi_readPacket()\fP are used in a multithreaded application, this mutex must be locked before calling \fBbrlapi_writePacket()\fP or \fBbrlapi_readPacket()\fP, and unlocked afterwards\&. .SH "Author" .PP Generated automatically by Doxygen for BrlAPI from the source code\&.