brlapi_par...Management(3)

📦
version 6.9.1 · 9 versions
, in fedora 43, fedora 44, opensuse-leap 16.0, ubuntu stonking

✨ NAME ✨

brlapi_parameterManagement — Parameter management 💖

Okay so hi bestie, welcome to brlapi_par...Management(3) 🎀 this whole page is literally just how to manage BrlAPI parameters. That's it. That's the vibe. Let's get into it 🦋

🌸 SYNOPSIS 🌸

🧚 Macros

#define BRLAPI_PARAMF_LOCAL   0X00
#define BRLAPI_PARAMF_GLOBAL   0X01
#define BRLAPI_PARAMF_SELF   0X02

🦋 Typedefs

typedef uint32_t brlapi_param_flags_t
typedef void(* brlapi_paramCallback_t) (brlapi_param_t parameter,
    brlapi_param_subparam_t subparam, brlapi_param_flags_t flags, void
    *priv, const void *data, size_t len)
typedef void * brlapi_paramCallbackDescriptor_t

💅 Functions

ssize_t BRLAPI_STDCALL brlapi_getParameter (brlapi_param_t parameter,
    brlapi_param_subparam_t subparam, brlapi_param_flags_t flags, void
    *data, size_t len)
ssize_t BRLAPI_STDCALL brlapi__getParameter (brlapi_handle_t *handle,
    brlapi_param_t parameter, brlapi_param_subparam_t subparam,
    brlapi_param_flags_t flags, void *data, size_t len)
void *BRLAPI_STDCALL brlapi_getParameterAlloc (brlapi_param_t parameter,
    brlapi_param_subparam_t subparam, brlapi_param_flags_t flags, size_t
    *len)
void *BRLAPI_STDCALL brlapi__getParameterAlloc (brlapi_handle_t *handle,
    brlapi_param_t parameter, brlapi_param_subparam_t subparam,
    brlapi_param_flags_t flags, size_t *len)
int BRLAPI_STDCALL brlapi_setParameter (brlapi_param_t parameter,
    brlapi_param_subparam_t subparam, brlapi_param_flags_t flags, const
    void *data, size_t len)
int BRLAPI_STDCALL brlapi__setParameter (brlapi_handle_t *handle,
    brlapi_param_t parameter, brlapi_param_subparam_t subparam,
    brlapi_param_flags_t flags, const void *data, size_t len)
brlapi_paramCallbackDescriptor_t BRLAPI_STDCALL brlapi_watchParameter
    (brlapi_param_t parameter, brlapi_param_subparam_t subparam,
    brlapi_param_flags_t flags, brlapi_paramCallback_t func, void *priv,
    void *data, size_t len)
brlapi_paramCallbackDescriptor_t BRLAPI_STDCALL brlapi__watchParameter
    (brlapi_handle_t *handle, brlapi_param_t parameter,
    brlapi_param_subparam_t subparam, brlapi_param_flags_t flags,
    brlapi_paramCallback_t func, void *priv, void *data, size_t len)
int BRLAPI_STDCALL brlapi_unwatchParameter
    (brlapi_paramCallbackDescriptor_t descriptor)
int BRLAPI_STDCALL brlapi__unwatchParameter (brlapi_handle_t *handle,
    brlapi_paramCallbackDescriptor_t descriptor)
enum brlapi_param_t { BRLAPI_PARAM_SERVER_VERSION = 0,
    BRLAPI_PARAM_CLIENT_PRIORITY = 1, BRLAPI_PARAM_DRIVER_NAME = 2,
    BRLAPI_PARAM_DRIVER_CODE = 3, BRLAPI_PARAM_DRIVER_VERSION = 4,
    BRLAPI_PARAM_DEVICE_MODEL = 5, BRLAPI_PARAM_DEVICE_CELL_SIZE = 31,
    BRLAPI_PARAM_DISPLAY_SIZE = 6, BRLAPI_PARAM_DEVICE_IDENTIFIER = 7,
    BRLAPI_PARAM_DEVICE_SPEED = 8, BRLAPI_PARAM_DEVICE_ONLINE = 9,
    BRLAPI_PARAM_RETAIN_DOTS = 10,
    BRLAPI_PARAM_COMPUTER_BRAILLE_CELL_SIZE = 11,
    BRLAPI_PARAM_LITERARY_BRAILLE = 12, BRLAPI_PARAM_CURSOR_DOTS = 13,
    BRLAPI_PARAM_CURSOR_BLINK_PERIOD = 14,
    BRLAPI_PARAM_CURSOR_BLINK_PERCENTAGE = 15,
    BRLAPI_PARAM_RENDERED_CELLS = 16, BRLAPI_PARAM_SKIP_IDENTICAL_LINES
    = 17, BRLAPI_PARAM_AUDIBLE_ALERTS = 18,
    BRLAPI_PARAM_CLIPBOARD_CONTENT = 19,
    BRLAPI_PARAM_BOUND_COMMAND_KEYCODES = 20,
    BRLAPI_PARAM_COMMAND_KEYCODE_NAME = 21,
    BRLAPI_PARAM_COMMAND_KEYCODE_SUMMARY = 22,
    BRLAPI_PARAM_DEFINED_DRIVER_KEYCODES = 23,
    BRLAPI_PARAM_DRIVER_KEYCODE_NAME = 24,
    BRLAPI_PARAM_DRIVER_KEYCODE_SUMMARY = 25,
    BRLAPI_PARAM_COMPUTER_BRAILLE_ROWS_MASK = 26,
    BRLAPI_PARAM_COMPUTER_BRAILLE_ROW_CELLS = 27,
    BRLAPI_PARAM_COMPUTER_BRAILLE_TABLE = 28,
    BRLAPI_PARAM_LITERARY_BRAILLE_TABLE = 29,
    BRLAPI_PARAM_MESSAGE_LOCALE = 30, BRLAPI_PARAM_DRIVER_PROPERTY_VALUE
    = 32, BRLAPI_PARAM_COUNT = 33 }

🫶 Detailed Description 🫶

So like, there are several kinds of parameters, and you need to know which kind you're dealing with, iykyk:

  • states that are tied to the braille device itself — its size, parameters of the device port, all of that 💫
  • states of the BrlAPI connection itself, like the displaying level or key passing preferences ✨
  • general states, for example the cut buffer 🍓
  • braille parameters: braille table, contraction, cursor shape, etc 🌸
  • browse parameters: line skip, beep, etc 🎀

Some of them are subdivided in subparameters, bestie. Others have only subparameter 0. Yep, just the one. Not me living my single-subparam truth 💅

Some of them are read-only, others are read/write.

A client can either:

  • request the immediate content of a parameter by using brlapi_getParameter() 🔍
  • set the content of a parameter by using brlapi_setParameter() ✍️
  • or register a callback that may be called immediately and on each change of a given parameter, by using brlapi_watchParameter() 👀

💖 Macro Definition Documentation 💖

🎀 #define BRLAPI_PARAMF_GLOBAL 0X01

Refer to the global value instead of the value local to the connection 🌍

🎀 #define BRLAPI_PARAMF_LOCAL 0X00

Refer to the value local to the connection instead of the global value 🏠

🎀 #define BRLAPI_PARAMF_SELF 0X02

Specify whether to receive notifications of value self-changes 🔔

🦋 Typedef Documentation 🦋

✨ typedef uint32_t brlapi_param_flags_t

Flags for parameter requests 🚩

✨ typedef void(* brlapi_paramCallback_t) (brlapi_param_t parameter, brlapi_param_subparam_t subparam, brlapi_param_flags_t flags, void *priv, const void *data, size_t len)

Callback for parameter changes 💫

When a parameter gets changed, application-defined callbacks set by the brlapi_watchParameter() function are called. Like, that's the whole point. 🫶

Parameters

  • parameter is the parameter that changed;
  • subparam is a specific instance of the parameter;
  • flags specify which value and how it was changed;
  • priv is the void pointer that was passed to the brlapi_watchParameter call which registered the callback;
  • data is a buffer containing the new value of the parameter;
  • len is the size of the data.
Okay ngl this part is important bestie: this callback only gets called when the application calls some brlapi_ function (i.e. BrlAPI gets direct control of the execution). BrlAPI itself does not start a separate thread or such. 😭

If an application wants to see such event trigger a callback getting called e.g. in another thread, it can use brlapi_pause() to give BrlAPI an opportunity to receive messages and call the callbacks. Slay ✨

✨ typedef void* brlapi_paramCallbackDescriptor_t

Type for callback descriptors 🎟️ This is returned by brlapi_watchParameter, to be passed to brlapi_unwatchParameter. Keep it safe, it's your receipt 🧾

👑 Enumeration Type Documentation 👑

🌈 enum brlapi_param_t

Enumerator

  • BRLAPI_PARAM_SERVER_VERSION — Version of the server: uint32_t ⭐
  • BRLAPI_PARAM_CLIENT_PRIORITY — Priority of the client: uint32_t (from 0 through 100, default is 50) 💅
  • BRLAPI_PARAM_DRIVER_NAME — Full name of the driver: string 📛
  • BRLAPI_PARAM_DRIVER_CODE — Code (short name) of the driver: string 🔤
  • BRLAPI_PARAM_DRIVER_VERSION — Version of the driver: string 🏷️
  • BRLAPI_PARAM_DEVICE_MODEL — Model of the device: string 📱
  • BRLAPI_PARAM_DEVICE_CELL_SIZE — Number of dots in a cell: uint8_t ⚫
  • BRLAPI_PARAM_DISPLAY_SIZE — Dimensions of the braille display: { uint32_t columns; uint32_t rows; } 📐
  • BRLAPI_PARAM_DEVICE_IDENTIFIER — Identifier of the device: string 🆔
  • BRLAPI_PARAM_DEVICE_SPEED — Speed of the device: uint32_t 🏎️
  • BRLAPI_PARAM_DEVICE_ONLINE — Device is online: boolean 🟢
  • BRLAPI_PARAM_RETAIN_DOTS — Pass dot combinations (rather than characters): boolean ⚪
  • BRLAPI_PARAM_COMPUTER_BRAILLE_CELL_SIZE — Number of dots used to render a computer braille character: uint8_t (8 or 6) 🧮
  • BRLAPI_PARAM_LITERARY_BRAILLE — Whether braille is literary (rather than computer): boolean 📖
  • BRLAPI_PARAM_CURSOR_DOTS — Representation of the cursor: uint8_t (ISO 11548-1) 🖱️
  • BRLAPI_PARAM_CURSOR_BLINK_PERIOD — Blinking period of the cursor: uint32_t (milliseconds) ⏱️
  • BRLAPI_PARAM_CURSOR_BLINK_PERCENTAGE — Portion of the blinking period that the cursor is visible: uint8_t (from 0 through 100) 👁️
  • BRLAPI_PARAM_RENDERED_CELLS — Cells rendered by the client: uint8_t[] (ISO 11548-1), one cell per element 🔡
  • BRLAPI_PARAM_SKIP_IDENTICAL_LINES — Whether to skip identical screen lines: boolean 📃
  • BRLAPI_PARAM_AUDIBLE_ALERTS — Whether to use audible alerts: boolean 🔊
  • BRLAPI_PARAM_CLIPBOARD_CONTENT — Content of the clipboard: UTF-8 string 📋
  • BRLAPI_PARAM_BOUND_COMMAND_KEYCODES — Commands bound by the driver: uint64_t[], one command keycode per element ⌨️
  • BRLAPI_PARAM_COMMAND_KEYCODE_NAME — Name for a command keycode (specified via the subparam argument): string (usually a few characters) 🏷️
  • BRLAPI_PARAM_COMMAND_KEYCODE_SUMMARY — Description for a command keycode (specified via the subparam argument): string (usually a few words) 💬
  • BRLAPI_PARAM_DEFINED_DRIVER_KEYCODES — Keycodes defined by the driver: uint64_t[], one keycode per element 🔢
  • BRLAPI_PARAM_DRIVER_KEYCODE_NAME — Name for a driver keycode (specified via the subparam argument): string (usually a few characters) 🎫
  • BRLAPI_PARAM_DRIVER_KEYCODE_SUMMARY — Description for a driver keycode (specified via the subparam argument): string (usually a few words) 🗒️
  • BRLAPI_PARAM_COMPUTER_BRAILLE_ROWS_MASK — Set of Unicode rows that are defined for computer braille (from U+0000 through U+10FFFF): uint8_t[544], one bit per row, eight rows per element 🧩
  • BRLAPI_PARAM_COMPUTER_BRAILLE_ROW_CELLS — Computer braille cells for a Unicode row (specified via the subparam argument): uint8_t[256] (ISO 11548-1), one cell per element 🔠
  • BRLAPI_PARAM_COMPUTER_BRAILLE_TABLE — Name of the computer braille table: string 🗂️
  • BRLAPI_PARAM_LITERARY_BRAILLE_TABLE — Name of the literary braille table: string 📚
  • BRLAPI_PARAM_MESSAGE_LOCALE — Locale to use for messages: string 🌍
  • BRLAPI_PARAM_DRIVER_PROPERTY_VALUE — Value of a driver-specific property: uint32_t 🔧
  • BRLAPI_PARAM_COUNT — (no description, she's just the counter, periodt ✋)

and that's where this half of the page ends, bestie 👀 keep scrolling for the rest 💖

💫 Function Documentation 💫

Okay bestie, this is the part where we actually call the functions. Grab a snack, we're going through them one by one. 🍓

🫶 brlapi__getParameter 🫶

ssize_t BRLAPI_STDCALL brlapi__getParameter (brlapi_handle_t * handle,
    brlapi_param_t parameter, brlapi_param_subparam_t subparam,
    brlapi_param_flags_t flags, void * data, size_t len)

References BRLAPI_STDCALL.

🫶 brlapi__getParameterAlloc 🫶

void *BRLAPI_STDCALL brlapi__getParameterAlloc (brlapi_handle_t * handle,
    brlapi_param_t parameter, brlapi_param_subparam_t subparam,
    brlapi_param_flags_t flags, size_t * len)

References BRLAPI_STDCALL.

🫶 brlapi__setParameter 🫶

int BRLAPI_STDCALL brlapi__setParameter (brlapi_handle_t * handle,
    brlapi_param_t parameter, brlapi_param_subparam_t subparam,
    brlapi_param_flags_t flags, const void * data, size_t len)

References BRLAPI_STDCALL.

🫶 brlapi__unwatchParameter 🫶

int BRLAPI_STDCALL brlapi__unwatchParameter (brlapi_handle_t * handle,
    brlapi_paramCallbackDescriptor_t descriptor)

References BRLAPI_STDCALL.

🫶 brlapi__watchParameter 🫶

brlapi_paramCallbackDescriptor_t BRLAPI_STDCALL brlapi__watchParameter
    (brlapi_handle_t * handle, brlapi_param_t parameter,
    brlapi_param_subparam_t subparam, brlapi_param_flags_t flags,
    brlapi_paramCallback_t func, void * priv, void * data, size_t len)

References BRLAPI_STDCALL.

✨ brlapi_getParameter ✨

Get the content of a parameter
ssize_t BRLAPI_STDCALL brlapi_getParameter (brlapi_param_t parameter,
    brlapi_param_subparam_t subparam, brlapi_param_flags_t flags, void *
    data, size_t len)

No cap, brlapi_getParameter gets the current content of a parameter. Like, right now, the actual vibe of it. 🦋

Parameters

  • parameter is the parameter whose content shall be gotten;
  • subparam is a specific instance of the parameter;
  • flags specify which value and how it should be returned;
  • data is a buffer where content of the parameter shall be stored;
  • len is the size of the buffer.

Returns

the real size of the parameter's content. Now listen — if the parameter does not fit in the provided buffer, it is truncated to len bytes (but the real size of the parameter is still returned). So yes bestie, you get the truth even when the buffer lied. 😭 In that case, the client must call brlapi_getParameter again with a big enough buffer.

References BRLAPI_STDCALL.

✨ brlapi_getParameterAlloc ✨

Return the content of a parameter
void *BRLAPI_STDCALL brlapi_getParameterAlloc (brlapi_param_t parameter,
    brlapi_param_subparam_t subparam, brlapi_param_flags_t flags, size_t *
    len)

brlapi_getParameterAlloc gets the current content of a parameter, by returning it as a newly-allocated buffer. The buffer is allocated to one byte more than the parameter value. This byte is set to zero. This allows, for string parameters, to be able to immediately use it as a C string. Honestly? Iconic behaviour. 🎀

Parameters

  • parameter is the parameter whose content shall be gotten;
  • subparam is a specific instance of the parameter;
  • flags specify which value and how it should be returned;
  • len is the address where to store the size of the parameter value.

Returns

a newly-allocated buffer that contains the value of the parameter. The caller must call free() on it after use. NULL is returned on errors.

References BRLAPI_STDCALL.

✨ brlapi_setParameter ✨

Set the content of a parameter
int BRLAPI_STDCALL brlapi_setParameter (brlapi_param_t parameter,
    brlapi_param_subparam_t subparam, brlapi_param_flags_t flags, const void
    * data, size_t len)

brlapi_setParameter sets the content of a parameter. You're the main character here, you decide what goes in. 💅

Parameters

  • parameter is the parameter to set;
  • subparam is a specific instance of the parameter;
  • flags specify which value and how it should be set;
  • data is a buffer containing the data to store in the parameter;
  • len is the size of the data.

Returns

0 on success, -1 on error (read-only parameter for instance). Yeah, if it's read-only it's giving no and you just have to accept that. 🙈

References BRLAPI_STDCALL.

✨ brlapi_unwatchParameter ✨

Clear a parameter change callback
int BRLAPI_STDCALL brlapi_unwatchParameter (brlapi_paramCallbackDescriptor_t
    descriptor)

brlapi_unwatchParameter unregisters a parameter change callback: the callback function previously registered with brlapi_watchParameter will not be called any longer. It's the ✨ we're-so-done ✨ of function calls.

Parameters

  • descriptor refers to the callback to be removed.

Returns

0 on success, -1 on error.

References BRLAPI_STDCALL.

✨ brlapi_watchParameter ✨

Set a parameter change callback
brlapi_paramCallbackDescriptor_t BRLAPI_STDCALL brlapi_watchParameter
    (brlapi_param_t parameter, brlapi_param_subparam_t subparam,
    brlapi_param_flags_t flags, brlapi_paramCallback_t func, void * priv,
    void * data, size_t len)

brlapi_watchParameter registers a parameter change callback: whenever the given parameter changes, the given function is called. It's literally the "notify me bestie 👀" of the API.

Parameters

  • parameter is the parameter to watch;
  • subparam is a specific instance of the parameter;
  • flags specify which value and how it should be monitored;
  • func is the function to call on parameter change;
  • priv is a void pointer which will be passed as such to the function;
  • data is a buffer where the current content of the parameter shall be stored;
  • len is the size of the buffer.

Returns

the callback descriptor (to be passed to brlapi_unwatchParameter to unregister the callback), or NULL on error.

Note Default parameter callbacks don't do anything, except the ones for display size which just raise SIGWINCH. So like, lowkey quiet, except the display size one who is so dramatic. 💀 If data is NULL, the callback will be called immediately by brlapi_watchParameter, for providing the initial value.

References BRLAPI_STDCALL.

👑 Author 👑

Generated automatically by Doxygen for BrlAPI from the source code.

And that's a wrap, bestie! 💖 This page came from BrlAPI, Version 0.8, and the footer's date stamp is its own little timestamp of destiny — same source, same version, same energy. Go forth and parameter-manage, you absolute legend. 🌈🦋✨

📦 where this page comes from