.TH "BrlAPI's protocol" 3 "15 Jan 2004" "BrlAPI" \" -*- nroff -*-
.ad l
.nh
.SH NAME
BrlAPI's protocol \- Instructions and constants for \fIBrlAPI\fP 's protocol. 
More...
.SS "Defines"

.in +1c
.ti -1c
.RI "#define \fBBRLAPI_MAXPACKETSIZE\fP   512"
.br
.ti -1c
.RI "#define \fBBRLPACKET_AUTHKEY\fP   'K'"
.br
.ti -1c
.RI "#define \fBBRLPACKET_BYE\fP   'B'"
.br
.ti -1c
.RI "#define \fBBRLPACKET_GETDRIVERID\fP   'd'"
.br
.ti -1c
.RI "#define \fBBRLPACKET_GETDRIVERNAME\fP   'n'"
.br
.ti -1c
.RI "#define \fBBRLPACKET_GETDISPLAYSIZE\fP   's'"
.br
.ti -1c
.RI "#define \fBBRLPACKET_GETTTY\fP   't'"
.br
.ti -1c
.RI "#define \fBBRLPACKET_LEAVETTY\fP   'L'"
.br
.ti -1c
.RI "#define \fBBRLPACKET_KEY\fP   'k'"
.br
.ti -1c
.RI "#define \fBBRLPACKET_COMMAND\fP   'c'"
.br
.ti -1c
.RI "#define \fBBRLPACKET_MASKKEYS\fP   'm'"
.br
.ti -1c
.RI "#define \fBBRLPACKET_UNMASKKEYS\fP   'u'"
.br
.ti -1c
.RI "#define \fBBRLPACKET_WRITE\fP   'W'"
.br
.ti -1c
.RI "#define \fBBRLPACKET_WRITEDOTS\fP   'D'"
.br
.ti -1c
.RI "#define \fBBRLPACKET_STATWRITE\fP   'S'"
.br
.ti -1c
.RI "#define \fBBRLPACKET_GETRAW\fP   '*'"
.br
.ti -1c
.RI "#define \fBBRLPACKET_LEAVERAW\fP   '#'"
.br
.ti -1c
.RI "#define \fBBRLPACKET_PACKET\fP   'p'"
.br
.ti -1c
.RI "#define \fBBRLPACKET_ACK\fP   'A'"
.br
.ti -1c
.RI "#define \fBBRLPACKET_ERROR\fP   'E'"
.br
.ti -1c
.RI "#define \fBBRLRAW_MAGIC\fP   (0xdeadbeefL)"
.br
.in -1c
.SS "Typedefs"

.in +1c
.ti -1c
.RI "typedef uint32_t \fBbrl_type_t\fP"
.br
.in -1c
.SS "Functions"

.in +1c
.ti -1c
.RI "int \fBbrlapi_writePacket\fP (int fd, \fBbrl_type_t\fP type, const void *buf, size_t size)"
.br
.ti -1c
.RI "int \fBbrlapi_readPacket\fP (int fd, \fBbrl_type_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_MAXPACKETSIZE   512"
.PP
Maximum packet size for packets exchanged on sockets and with braille terminal 
.SS "#define BRLPACKET_ACK   'A'"
.PP
Acknowledgement 
.SS "#define BRLPACKET_AUTHKEY   'K'"
.PP
Authentication key 
.SS "#define BRLPACKET_BYE   'B'"
.PP
Bye 
.SS "#define BRLPACKET_COMMAND   'c'"
.PP
braille command 
.SS "#define BRLPACKET_ERROR   'E'"
.PP
Error in protocol 
.SS "#define BRLPACKET_GETDISPLAYSIZE   's'"
.PP
Dimensions of brl display 
.SS "#define BRLPACKET_GETDRIVERID   'd'"
.PP
Ask which driver is used 
.SS "#define BRLPACKET_GETDRIVERNAME   'n'"
.PP
Ask which driver is used 
.SS "#define BRLPACKET_GETRAW   '*'"
.PP
Enter in raw mode 
.SS "#define BRLPACKET_GETTTY   't'"
.PP
asks for a specified tty 
.SS "#define BRLPACKET_KEY   'k'"
.PP
braille key 
.SS "#define BRLPACKET_LEAVERAW   '#'"
.PP
Leave raw mode 
.SS "#define BRLPACKET_LEAVETTY   'L'"
.PP
release the tty 
.SS "#define BRLPACKET_MASKKEYS   'm'"
.PP
Mask a key-range 
.SS "#define BRLPACKET_PACKET   'p'"
.PP
Raw packets 
.SS "#define BRLPACKET_STATWRITE   'S'"
.PP
Write Status Cells 
.SS "#define BRLPACKET_UNMASKKEYS   'u'"
.PP
Unmask key range 
.SS "#define BRLPACKET_WRITE   'W'"
.PP
Write On Braille Display 
.SS "#define BRLPACKET_WRITEDOTS   'D'"
.PP
Write Dots On Braille Display 
.SS "#define BRLRAW_MAGIC   (0xdeadbeefL)"
.PP
Magic number to give when sending a BRLPACKET_GETRAW packet 
.SH "TYPEDEF DOCUMENTATION"
.PP 
.SS "typedef uint32_t brl_type_t"
.PP
type for packet type. Only unsigned can cross networks, 32bits 
.SH "FUNCTION DOCUMENTATION"
.PP 
.SS "int brlapi_readPacket (int fd, \fBbrl_type_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
.in +1c
packet's size, -2 if \fCEOF\fP occurred, -1 on error 
.SS "int brlapi_writePacket (int fd, \fBbrl_type_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
.in +1c
0 on success, -1 on failure 
.SH "VARIABLE DOCUMENTATION"
.PP 
.SS "pthread_mutex_t brlapi_fd_mutex"
.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
.TP
\fBbrlapi_initializeConnection()\fP
.TP
\fBbrlapi_closeConnection()\fP
.TP
\fBbrlapi_getRaw()\fP
.TP
\fBbrlapi_leaveRaw()\fP
.TP
\fBbrlapi_sendRaw()\fP
.TP
\fBbrlapi_recvRaw()\fP
.TP
\fBbrlapi_getDriverId()\fP
.TP
\fBbrlapi_getDriverName()\fP
.TP
\fBbrlapi_getDisplaySize()\fP
.TP
\fBbrlapi_getTty()\fP
.TP
\fBbrlapi_leaveTty()\fP
.TP
brlapi_write*()
.TP
brlapi_(un)?ignorekeys()
.TP
brlapi_read*()
.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.