brlapi_parameterManagement(3)       BrlAPI       brlapi_parameterManagement(3)



NAME
       brlapi_parameterManagement - How to manage BrlAPI parameters.


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
       There are several kinds of parameters:

       +o states associated with the braille device itself, such as its size or
         parameters of the device port

       +o states of the BrlAPI connection itself, such as the displaying level
         or key passing preferences.

       +o general states such as the cut buffer,

       +o braille parameters: braille table, contraction, cursor shape, etc,

       +o browse parameters: line skip, beep, etc.

       Some of them are subdivided in subparameters. Others have only
       subparameter 0.

       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.

       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.

       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.

   typedef void* brlapi_paramCallbackDescriptor_t
       Type for callback descriptors This is returned by
       brlapi_watchParameter, to be passed to brlapi_unwatchParameter.

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

Function Documentation
   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_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_handle_t * handle,
       brlapi_param_t parameter, brlapi_param_subparam_t subparam,
       brlapi_param_flags_t flags, const void * data, size_t len)
   int BRLAPI_STDCALL brlapi__unwatchParameter (brlapi_handle_t * handle,
       brlapi_paramCallbackDescriptor_t descriptor)
   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)
   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)
       Get the content of a parameter

       brlapi_getParameter gets the current content of a parameter

       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. 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). In that case, the
           client must call brlapi_getParameter again with a big enough
           buffer.

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

       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.

       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

   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)
       Set the content of a parameter

       brlapi_setParameter sets the content of a parameter

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

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

       brlapi_unwatchParameter unregisters a parameter change callback: the
       callback function previously registered with brlapi_watchParameter will
       not be called any longer.

       Parameters
           descriptor refers to the callback to be removed.

       Returns
           0 on success, -1 on error.

   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)
       Set a parameter change callback

       brlapi_watchParameter registers a parameter change callback: whenever
       the given parameter changes, the given function is called.

       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.

           If data is NULL, the callback will be called immediately by
           brlapi_watchParameter, for providing the initial value

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



Version 0.8                     Mon Apr 6 2026   brlapi_parameterManagement(3)
