Connecting to BrlAPI(3) BrlAPI Connecting to BrlAPI(3)NAME
Connecting to BrlAPI -
Data Structures
struct brlapi_settings_t
Settings structure for BrlAPI connection.
Defines
#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
Functions
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)
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 not needed any more,
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_DEFAUTHPATH 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_MAXNAMELENGTH 31
Maximum name length for names embeded in BrlAPI packets
#define BRLAPI_MAXPACKETSIZE 512
Maximum packet size for packets exchanged on sockets and with braille
terminal
#define BRLAPI_SOCKETPATH '/var/lib/BrlAPI/'
Default unix path on which connections to BrlAPI can be established
#define BRLAPI_SOCKETPORTNUM 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_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. 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: %s0,
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()
int brlapi_loadAuthKey (const char * filename, size_t * 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:
0, -1 on error
See also:
brlapi_settings_t, brlapi_initializeConnectionVersion 1.0 26 Dec 2005 Connecting to BrlAPI(3)
