---
name: "brlapi_connection"
section: "3"
platform: "linux"
package: "libbrlapi-dev"
version: "6.7-3.1+deb13u3"
release: "Debian 13 (Trixie)"
platforms: ["linux"]
url: "https://new.carta.tech/brlapi_connection"
---

# brlapi\_connection(3)

Connecting to BrlAPI

## NAME

brlapi\_connection - Connecting to BrlAPI

## SYNOPSIS

### Data Structures

struct **brlapi\_connectionSettings\_t**\
 Settings structure for *BrlAPI* connection.

### Macros

\#define **BRLAPI\_SOCKETPORTNUM**   4101\
 \#define **BRLAPI\_SOCKETPORT**   '4101'\
 \#define **BRLAPI\_SOCKETPATH**   '/var/lib/BrlAPI'\
 \#define **BRLAPI\_ETCDIR**   '/etc'\
 \#define **BRLAPI\_AUTHKEYFILE**   'brlapi.key'\
 \#define **BRLAPI\_DEFAUTH\_KEYFILE**   'keyfile:' **BRLAPI\_ETCDIR** '/' **BRLAPI\_AUTHKEYFILE**\
 \#define **BRLAPI\_DEFAUTH\_POLKIT**   ''\
 \#define **BRLAPI\_DEFAUTH**   **BRLAPI\_DEFAUTH\_KEYFILE** **BRLAPI\_DEFAUTH\_POLKIT**\
 \#define **BRLAPI\_INVALID\_FILE\_DESCRIPTOR**   -1\
 \#define **BRLAPI\_SETTINGS\_INITIALIZER**   { NULL, NULL }\

### Typedefs

typedef int **brlapi\_fileDescriptor**\

### Functions

**brlapi\_fileDescriptor** **BRLAPI\_STDCALL** **brlapi\_openConnection** (const **brlapi\_connectionSettings\_t** \*desiredSettings, **brlapi\_connectionSettings\_t** \*actualSettings)\
 **brlapi\_fileDescriptor** **BRLAPI\_STDCALL** **brlapi\_\_openConnection** (**brlapi\_handle\_t** \*handle, const **brlapi\_connectionSettings\_t** \*desiredSettings, **brlapi\_connectionSettings\_t** \*actualSettings)\
 **brlapi\_fileDescriptor** **BRLAPI\_STDCALL** **brlapi\_getFileDescriptor** (void)\
 **brlapi\_fileDescriptor** **BRLAPI\_STDCALL** **brlapi\_\_getFileDescriptor** (**brlapi\_handle\_t** \*handle)\
 void **BRLAPI\_STDCALL** **brlapi\_closeConnection** (void)\
 void **BRLAPI\_STDCALL** **brlapi\_\_closeConnection** (**brlapi\_handle\_t** \*handle)\

## Detailed Description

Before calling any other function of the library, calling **brlapi\_openConnection()** 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.

## Macro Definition Documentation

### #define BRLAPI\_AUTHKEYFILE 'brlapi.key'

Default name of the file containing *BrlAPI* 's authorization key

This name is relative to BRLAPI\_ETCDIR

### #define BRLAPI\_DEFAUTH BRLAPI\_DEFAUTH\_KEYFILE BRLAPI\_DEFAUTH\_POLKIT

### #define BRLAPI\_DEFAUTH\_KEYFILE 'keyfile:' BRLAPI\_ETCDIR '/' BRLAPI\_AUTHKEYFILE

Default authorization setting

### #define BRLAPI\_DEFAUTH\_POLKIT ''

### #define BRLAPI\_ETCDIR '/etc'

*brltty* 's settings directory

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

### #define BRLAPI\_INVALID\_FILE\_DESCRIPTOR -1

Invalid value for brlapi\_fileDescriptor

This is returned by **brlapi\_getFileDescriptor()** when the connection is closed.

### #define BRLAPI\_SETTINGS\_INITIALIZER { NULL, NULL }

Allows to initialize a structure of type **brlapi\_connectionSettings\_t \* with default values.**

### #define BRLAPI\_SOCKETPATH '/var/lib/BrlAPI'

**Default unix path on which connections to** *BrlAPI* **can be established**

### #define BRLAPI\_SOCKETPORT '4101'

### #define BRLAPI\_SOCKETPORTNUM 4101

**Default port number on which connections to** *BrlAPI* **can be established**

## Typedef Documentation

### typedef int brlapi\_fileDescriptor

**OS-dependent file descriptor type**

**This is the type for file descriptors returned by brlapi\_openConnection() and brlapi\_getFileDescriptor().**

## Function Documentation

### void BRLAPI\_STDCALL brlapi\_\_closeConnection (brlapi\_handle\_t \* handle)

### brlapi\_fileDescriptor BRLAPI\_STDCALL brlapi\_\_getFileDescriptor (brlapi\_handle\_t \* handle)

### brlapi\_fileDescriptor BRLAPI\_STDCALL brlapi\_\_openConnection (brlapi\_handle\_t \* handle, const brlapi\_connectionSettings\_t \* desiredSettings, brlapi\_connectionSettings\_t \* actualSettings)

### void BRLAPI\_STDCALL 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\_openConnection() gave has no meaning any more**

### brlapi\_fileDescriptor BRLAPI\_STDCALL brlapi\_getFileDescriptor (void)

**Return the file descriptor used by the BrlAPI connection**

**This allows to use it with** `select()`**,** `g_io_add_watch()`**,** `XtAppAddInput()`**, etc.**

**BRLAPI\_INVALID\_FILE\_DESCRIPTOR is returned when the connection was closed.**

### brlapi\_fileDescriptor BRLAPI\_STDCALL brlapi\_openConnection (const brlapi\_connectionSettings\_t \* desiredSettings, brlapi\_connectionSettings\_t \* actualSettings)

**Open a socket and connect it to** *BrlAPI* **'s server**

**This function first loads an authorization 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 authorization key on the socket and waits for acknowledgement.**

**Returns**

**the file descriptor, or BRLAPI\_INVALID\_FILE\_DESCRIPTOR 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\_openConnection() may be called several times, but** *libbrlapi* **functions will always work with the last call's descriptor**

**Example:**

```
if (brlapi_openConnection(&settings,&settings)<0) {
 fprintf(stderr,"couldn't connect to BrlAPI at %s: %s\n",
  settings.host, brlapi_strerror(&brlapi_error));
 exit(1);
}
```

**Errors:**

*BrlAPI* **might not be on this TCP port, the host name might not be resolvable, the authorization may fail,...**

**Parameters**

*desiredSettings* **this gives the desired connection parameters, as described in brlapi\_connectionSettings\_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\_connectionSettings\_t structure when the user gave parameters to the program for instance;** \
 *actualSettings* **if not** `NULL`**, parameters which were actually used are stored here, if the application ever needs them. Since they are constant strings, or come from a getenv call, these must not be freed by the application.**

**See also**

**brlapi\_connectionSettings\_t brlapi\_writePacket() brlapi\_readPacketHeader() brlapi\_readPacketContent() brlapi\_readPacket()**

## Author

**Generated automatically by Doxygen for BrlAPI from the source code.**