.TH "BrlAPI's protocol" 3 "Sat Oct 25 2014" "Version 1.0" "BrlAPI" \" -*- nroff -*-
.ad l
.nh
.SH NAME
BrlAPI's protocol \- 
.PP
Instructions and constants for \fIBrlAPI\fP 's protocol\&.  

.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 "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   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 "Macro Definition Documentation"
.PP 
.SS "#define BRLAPI_AUTH_CRED   'C'"
Explicit socket credentials authorization 
.SS "#define BRLAPI_AUTH_KEY   'K'"
Key authorization 
.SS "#define BRLAPI_AUTH_NONE   'N'"
No or implicit authorization 
.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   512"
Maximum packet size for packets exchanged on sockets and with braille terminal 
.SS "#define BRLAPI_PACKET_ACCEPTKEYRANGES   'u'"
Unmask key ranges 
.SS "#define BRLAPI_PACKET_ACK   'A'"
Acknowledgement 
.SS "#define BRLAPI_PACKET_AUTH   'a'"
Authorization 
.SS "#define BRLAPI_PACKET_ENTERRAWMODE   '*'"
Enter in raw mode 
.SS "#define BRLAPI_PACKET_ENTERTTYMODE   't'"
Asks for a specified tty 
.SS "#define BRLAPI_PACKET_ERROR   'e'"
non-fatal error 
.SS "#define BRLAPI_PACKET_EXCEPTION   'E'"
Exception 
.SS "#define BRLAPI_PACKET_GETDISPLAYSIZE   's'"
Dimensions of brl display 
.SS "#define BRLAPI_PACKET_GETDRIVERNAME   'n'"
Ask which driver is used 
.SS "#define BRLAPI_PACKET_IGNOREKEYRANGES   'm'"
Mask key ranges 
.SS "#define BRLAPI_PACKET_KEY   'k'"
Braille key 
.SS "#define BRLAPI_PACKET_LEAVERAWMODE   '#'"
Leave raw mode 
.SS "#define BRLAPI_PACKET_LEAVETTYMODE   'L'"
Release the tty 
.SS "#define BRLAPI_PACKET_PACKET   'p'"
Raw packets 
.SS "#define BRLAPI_PACKET_RESUMEDRIVER   'R'"
Resume driver 
.SS "#define BRLAPI_PACKET_SETFOCUS   'F'"
Set current tty focus 
.SS "#define BRLAPI_PACKET_SUSPENDDRIVER   'S'"
Suspend driver 
.SS "#define BRLAPI_PACKET_VERSION   'v'"
Version 
.SS "#define BRLAPI_PACKET_WRITE   'w'"
Write 
.SS "#define BRLAPI_PROTOCOL_VERSION   ((uint32_t) 8) /** Communication protocol version */"

.SS "#define BRLAPI_WF_ATTR_AND   0X08"
And attributes 
.SS "#define BRLAPI_WF_ATTR_OR   0X10"
Or attributes 
.SS "#define BRLAPI_WF_CHARSET   0X40"
Charset 
.SS "#define BRLAPI_WF_CURSOR   0X20"
Cursor position 
.SS "#define BRLAPI_WF_DISPLAYNUMBER   0X01"
Flags for writing Display number 
.SS "#define BRLAPI_WF_REGION   0X02"
Region parameter 
.SS "#define BRLAPI_WF_TEXT   0X04"
Contains some text 
.SH "Function Documentation"
.PP 
.SS "ssize_t brlapi_readPacket (\fBbrlapi_fileDescriptor\fPfd, \fBbrlapi_packetType_t\fP *type, void *buf, size_tsize)"
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\fPfd, size_tpacketSize, void *buf, size_tbufSize)"
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\fPfd, \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\fPfd, \fBbrlapi_packetType_t\fPtype, const void *buf, size_tsize)"
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"
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\&. 
.SH "Author"
.PP 
Generated automatically by Doxygen for BrlAPI from the source code\&.