---
name: "brlapi_loadAuthKey"
section: "3"
platform: "linux"
package: "libbrlapi1-dev"
version: "3.7.2-7.1"
release: "Debian 4.0 (Etch)"
platforms: ["linux"]
url: "https://new.carta.tech/brlapi_connection"
---

# brlapi\_loadAuthKey(3)

Part of [brlapi\_connection(3)](/brlapi_connection/3.md).

## 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\_initializeConnection**