.TH "BrlAPI's protocol" 3 "7 Oct 2009" "Version 1.0" "BrlAPI" \" -*- nroff -*-
.ad l
.nh
.SH NAME
BrlAPI's protocol \- Instructions and constants for \fIBrlAPI\fP 's protocol.  

.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 "union \fBbrlapi_packet_t\fP"
.br
.in -1c
.SS "Defines"

.in +1c
.ti -1c
.RI "#define \fBBRLAPI_PROTOCOL_VERSION\fP   ((uint32_t) 8)"
.br
.ti -1c
.RI "#define \fBBRLAPI_MAXPACKETSIZE\fP   512"
.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_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_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
.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 "Define Documentation"
.PP 
.SS "#define BRLAPI_AUTH_CRED   'C'"
.PP
Explicit socket credentials authorization 
.SS "#define BRLAPI_AUTH_KEY   'K'"
.PP
Key authorization 
.SS "#define BRLAPI_AUTH_NONE   'N'"
.PP
No or implicit authorization 
.SS "#define BRLAPI_DEVICE_MAGIC   (0xdeadbeefL)"
.PP
Magic number to give when sending a BRLPACKET_ENTERRAWMODE or BRLPACKET_SUSPEND packet 
.SS "#define BRLAPI_HEADERSIZE   sizeof(\fBbrlapi_header_t\fP)"
.PP
Size of packet headers 
.SS "#define BRLAPI_MAXPACKETSIZE   512"
.PP
Maximum packet size for packets exchanged on sockets and with braille terminal 
.SS "#define BRLAPI_PACKET_ACCEPTKEYRANGES   'u'"
.PP
Unmask key ranges 
.SS "#define BRLAPI_PACKET_ACK   'A'"
.PP
Acknowledgement 
.SS "#define BRLAPI_PACKET_AUTH   'a'"
.PP
Authorization 
.SS "#define BRLAPI_PACKET_ENTERRAWMODE   '*'"
.PP
Enter in raw mode 
.SS "#define BRLAPI_PACKET_ENTERTTYMODE   't'"
.PP
Asks for a specified tty 
.SS "#define BRLAPI_PACKET_ERROR   'e'"
.PP
non-fatal error 
.SS "#define BRLAPI_PACKET_EXCEPTION   'E'"
.PP
Exception 
.SS "#define BRLAPI_PACKET_GETDISPLAYSIZE   's'"
.PP
Dimensions of brl display 
.SS "#define BRLAPI_PACKET_GETDRIVERNAME   'n'"
.PP
Ask which driver is used 
.SS "#define BRLAPI_PACKET_IGNOREKEYRANGES   'm'"
.PP
Mask key ranges 
.SS "#define BRLAPI_PACKET_KEY   'k'"
.PP
Braille key 
.SS "#define BRLAPI_PACKET_LEAVERAWMODE   '#'"
.PP
Leave raw mode 
.SS "#define BRLAPI_PACKET_LEAVETTYMODE   'L'"
.PP
Release the tty 
.SS "#define BRLAPI_PACKET_PACKET   'p'"
.PP
Raw packets 
.SS "#define BRLAPI_PACKET_RESUMEDRIVER   'R'"
.PP
Resume driver 
.SS "#define BRLAPI_PACKET_SETFOCUS   'F'"
.PP
Set current tty focus 
.SS "#define BRLAPI_PACKET_SUSPENDDRIVER   'S'"
.PP
Suspend driver 
.SS "#define BRLAPI_PACKET_VERSION   'v'"
.PP
Version 
.SS "#define BRLAPI_PACKET_WRITE   'w'"
.PP
Write 
.SS "#define BRLAPI_PROTOCOL_VERSION   ((uint32_t) 8)"
.PP
.SS "#define BRLAPI_WF_ATTR_AND   0X08"
.PP
And attributes 
.SS "#define BRLAPI_WF_ATTR_OR   0X10"
.PP
Or attributes 
.SS "#define BRLAPI_WF_CHARSET   0X40"
.PP
Charset 
.SS "#define BRLAPI_WF_CURSOR   0X20"
.PP
Cursor position 
.SS "#define BRLAPI_WF_DISPLAYNUMBER   0X01"
.PP
Flags for writing Display number 
.SS "#define BRLAPI_WF_REGION   0X02"
.PP
Region parameter 
.SS "#define BRLAPI_WF_TEXT   0X04"
.PP
Contains some text 
.SH "Function Documentation"
.PP 
.SS "ssize_t brlapi_readPacket (\fBbrlapi_fileDescriptor\fP fd, \fBbrlapi_packetType_t\fP * type, void * buf, size_t size)"
.PP
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)"
.PP
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)"
.PP
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)"
.PP
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 \fBbrlapi_fd_mutex\fP"
.PP
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
brlapi_getDriverId()
.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.