struct brlapi_settings_t

Settings structure for BrlAPI connection.

#define BRLAPI_SOCKETPORTNUM 35751

#define BRLAPI_MAXPACKETSIZE 512

#define BRLAPI_MAXNAMELENGTH 31

#define BRLAPI_SOCKETPATH '/var/lib/BrlAPI/'

#define BRLAPI_ETCDIR '/etc'

#define BRLAPI_AUTHFILE 'brlapi.key'

#define BRLAPI_DEFAUTHPATH BRLAPI_ETCDIR '/' BRLAPI_AUTHFILE

int brlapi_initializeConnection (const brlapi_settings_t *clientSettings, brlapi_settings_t *usedSettings)

void brlapi_closeConnection (void)

int brlapi_loadAuthKey (const char *filename, size_t *authlength, void *auth)

Default name of the file containing BrlAPI 's authentication key

This name is relative to BRLAPI_ETCDIR

Final path for default authentication key file

brltty 's settings directory

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

Maximum name length for names embeded in BrlAPI packets

Maximum packet size for packets exchanged on sockets and with braille terminal

Default unix path on which connections to BrlAPI can be established

Default port number on which connections to BrlAPI can be established

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

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. But that also means that brlapi_initializeConnection() may be called several times, but libbrlapi functions will always work with the last call's descriptor

Example:.RS 4

 if (brlapi_initializeConnection(&settings,&settings)<0) {
  fprintf(stderr,'couldn't connect to BrlAPI at %s: %sn',
   settings.hostName, brlapi_strerror(brlapi_errno));
  exit(1);
 }

Errors:.RS 4 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_readPacketHeader() brlapi_readPacketContent() brlapi_readPacket()

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: 0, -1 on error

See also: brlapi_settings_t, brlapi_initializeConnection