brlapi_parameterManagement - Man Page

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

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

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 }

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

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

Specify whether to receive notifications of value self-changes

Flags for parameter requests

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

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

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

References BRLAPI_STDCALL​.

References BRLAPI_STDCALL​.

References BRLAPI_STDCALL​.

References BRLAPI_STDCALL​.

References BRLAPI_STDCALL​.

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

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

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

References BRLAPI_STDCALL​.

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

References BRLAPI_STDCALL​.

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