brlapi_connection(3)

💖 brlapi_connection — Connecting to BrlAPI 💖

okay so bestie, this one is from the Library Functions Manual, and it's literally the how do i even talk to BrlAPI page. the whole vibe of this file is: connect, do stuff, disconnect. slay. 💅

---

✨ 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

bestie listen. before you call any other function in this library, you gotta call brlapi_openConnection() first — that's the whole setup to actually establish a connection to BrlAPI's server. no connection, no nothing. 🫶

and when you're done and you don't need that connection anymore? brlapi_closeConnection() must be called to close it. like, mandatory. don't just ghost the server. 😭

---

🎀 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)

References BRLAPI_STDCALL.

brlapi_fileDescriptor BRLAPI_STDCALL brlapi__getFileDescriptor (brlapi_handle_t * handle)

References BRLAPI_STDCALL.

brlapi_fileDescriptor BRLAPI_STDCALL brlapi__openConnection (brlapi_handle_t * handle, const brlapi_connectionSettings_t * desiredSettings, brlapi_connectionSettings_t * actualSettings)

References BRLAPI_STDCALL.

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. like, it's gone gone. 🙈

References BRLAPI_STDCALL.

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.

References BRLAPI_STDCALL.

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. no cap, that's just how it is. 💀

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,... 😭 (fr fr, so many ways for this to not work)

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()

References BRLAPI_STDCALL.

---

🫶 Author

Generated automatically by Doxygen for BrlAPI from the source code. 🤖✨

---

and that's the whole page bestie, periodt. 💖 this was BrlAPI, Version 0.8, and the page is brlapi_connection(3) — now go open that connection and slay 👑🌈💅