---
name: "brlapi__unwatchParameter"
section: "3"
platform: "linux"
package: "libbrlapi-dev"
version: "6.7-3.1+deb13u3"
release: "Debian 13 (Trixie)"
platforms: ["linux"]
url: "https://new.carta.tech/brlapi_parameterManagement"
---

# brlapi\_\_unwatchParameter(3)

Parameter management - How to manage BrlAPI parameters.

Part of [brlapi\_parameterManagement(3)](/brlapi_parameterManagement/3.md).

## NAME

brlapi\_parameterManagement - Parameter management

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

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

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

### 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.*