Main Page | Modules | Data Structures | File List | Data Fields | Globals

Connecting to BrlAPI


Data Structures

struct  brlapi_settings_t
 Settings structure for BrlAPI connection. More...

Defines

#define BRLAPI_SOCKETPORT   "35751"
#define BRLAPI_ETCDIR   "/etc"
#define BRLAPI_AUTHFILE   "brlapi.key"
#define BRLAPI_AUTHNAME   BRLAPI_ETCDIR "/" BRLAPI_AUTHFILE

Functions

int brlapi_initializeConnection (const brlapi_settings_t *clientSettings, brlapi_settings_t *usedSettings)
void brlapi_closeConnection (void)
int brlapi_loadAuthKey (const char *filename, int *authlength, void *auth)
int brlapi_getControllingTty (void)

Detailed Description

Before calling any other function of the library, calling brlapi_initializeConnection() is needed to establish a connection to BrlAPI 's server. When the connection is no more needed, brlapi_closeConnection() must be called to close the connection.

Define Documentation

#define BRLAPI_AUTHFILE   "brlapi.key"
 

Default name of the file containing BrlAPI 's authentication key

This name is relative to BRLAPI_ETCDIR

#define BRLAPI_AUTHNAME   BRLAPI_ETCDIR "/" BRLAPI_AUTHFILE
 

Final path for default authentication key file

#define BRLAPI_ETCDIR   "/etc"
 

brltty 's settings directory

This is where authentication key and driver-dependent key names are found for instance.

#define BRLAPI_SOCKETPORT   "35751"
 

Default port number on which connections to BrlAPI can be established


Function Documentation

void brlapi_closeConnection void   ) 
 

Cleanly close the socket

This function locks until a closing acknowledgement is received from the server. The socket is then freed, so the file descriptor brlapi_initializeConnection() gave has no meaning any more

int brlapi_getControllingTty void   ) 
 

Return the number of the caller's controlling terminal

BrlAPI needs to know on which VT the application is connected. This function tries to find it out. It first looks for the CONTROLTTY environment variable, then tries to get it from /proc/self/stat

Hence people has to modify their xinitrc & xsession so that CONTROLTTY is set to 7 for instance, if the X server is launched on VT 7. The value can be got by grepping "using VT number [0-9]*" from X's log.

I personnaly have

CONTROLVT="$(grep "using VT number" "/var/log/XFree86.$(echo "$DISPLAY" | sed -e "s/^.*::*\([0-9]*\).*$/\1/").log" | sed -e "s/^.*using VT number \([0-9]*\).*$/\1/")" export CONTROLVT

in my .xsession

People also have to set CONTROLTTY when working remotely (as well as BRLAPI_HOSTNAME)

Returns:
-1 if unknown or on error

int brlapi_initializeConnection const brlapi_settings_t clientSettings,
brlapi_settings_t usedSettings
 

open a socket and connect it to BrlAPI 's server

This function first loads an authentication key as specified in settings. It then creates a TCP socket and connects it to the specified machine, on the specified port. It writes the authentication key on the socket and waits for acknowledgement.

Returns:
the file descriptor, or -1 on error
Note:
The file descriptor is returned in case the client wants to communicate with the server without using libbrlapi functions. If it uses them however, it won't have to pass the file descriptor later, since the library keeps a copy of it
Example:
 if (brlapi_initializeConnection(&settings)<0) {
  fprintf(stderr,"couldn't connect to BrlAPI!\n");
  exit(1);
 }
Errors:
BrlAPI might not be on this TCP port, the host name might not be resolvable, the authentication may fail,...
Parameters:
clientSettings this gives the connection parameters, as described in brlapi_settings_t. If NULL, defaults values are used, so that it is generally a good idea to give NULL as default, and only fill a brlapi_settings_t structure when the user gave parameters to the program for instance.
usedSettings if not NULL, parameters which were actually used are stored here, if the application ever needs them.
See also:
brlapi_settings_t brlapi_loadAuthKey() brlapi_writePacket() brlapi_readPacket()

int brlapi_loadAuthKey const char *  filename,
int *  authlength,
void *  auth
 

Load an authentication key from the given file

Calling this function shouldn't be needed if brlapi_initializeConnection is used.

Parameters:
filename gives the full path of the file ;
authlength gives the size of the auth buffer ;
auth is a buffer where the function will store the authentication key
Returns:
the size of the key, -1 on error
See also:
brlapi_settings_t, brlapi_initializeConnection


Generated on Thu Oct 28 10:33:03 2004 for BrlAPI by  doxygen 1.3.9.1