BrlAPI: Parameter management

BrlAPI 0.8

Macros | Typedefs | Functions
Parameter management

How to manage BrlAPI parameters. More...

## 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:

- states associated with the braille device itself, such as its size or parameters of the device port
- states of the BrlAPI connection itself, such as the displaying level or key passing preferences.
- general states such as the cut buffer,
- braille parameters: braille table, contraction, cursor shape, etc,
- 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

## ◆ BRLAPI_PARAMF_GLOBAL

#define BRLAPI_PARAMF_GLOBAL 0X01

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

## ◆ BRLAPI_PARAMF_LOCAL

#define BRLAPI_PARAMF_LOCAL 0X00

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

## ◆ BRLAPI_PARAMF_SELF

#define BRLAPI_PARAMF_SELF 0X02

Specify whether to receive notifications of value self-changes

## Typedef Documentation

## ◆ brlapi_param_flags_t

typedef uint32_t brlapi_param_flags_t

Flags for parameter requests

## ◆ brlapi_paramCallback_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)

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.

## ◆ brlapi_paramCallbackDescriptor_t

typedef void* brlapi_paramCallbackDescriptor_t

Type for callback descriptors This is returned by brlapi_watchParameter, to be passed to brlapi_unwatchParameter.

## Enumeration Type Documentation

## ◆ brlapi_param_t

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

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

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.

References BRLAPI_STDCALL.

## ◆ brlapi_getParameterAlloc()

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

References BRLAPI_STDCALL.

## ◆ brlapi_setParameter()

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

References BRLAPI_STDCALL.

## ◆ brlapi_unwatchParameter()

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.

References BRLAPI_STDCALL.

## ◆ brlapi_watchParameter()

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

References BRLAPI_STDCALL.