.TH "brlapi_parameterManagement" 3 "Version 0.8" "BrlAPI" \" -*- nroff -*-
.ad l
.nh
.SH NAME
brlapi_parameterManagement \- Parameter management
.PP
 \- How to manage BrlAPI parameters\&.  

.SH SYNOPSIS
.br
.PP
.SS "Macros"

.in +1c
.ti -1c
.RI "#define \fBBRLAPI_PARAMF_LOCAL\fP   0X00"
.br
.ti -1c
.RI "#define \fBBRLAPI_PARAMF_GLOBAL\fP   0X01"
.br
.ti -1c
.RI "#define \fBBRLAPI_PARAMF_SELF\fP   0X02"
.br
.in -1c
.SS "Typedefs"

.in +1c
.ti -1c
.RI "typedef uint32_t \fBbrlapi_param_flags_t\fP"
.br
.ti -1c
.RI "typedef void(* \fBbrlapi_paramCallback_t\fP) (\fBbrlapi_param_t\fP parameter, \fBbrlapi_param_subparam_t\fP subparam, \fBbrlapi_param_flags_t\fP flags, void *priv, const void *data, size_t len)"
.br
.ti -1c
.RI "typedef void * \fBbrlapi_paramCallbackDescriptor_t\fP"
.br
.in -1c
.SS "Functions"

.in +1c
.ti -1c
.RI "ssize_t \fBBRLAPI_STDCALL\fP \fBbrlapi_getParameter\fP (\fBbrlapi_param_t\fP parameter, \fBbrlapi_param_subparam_t\fP subparam, \fBbrlapi_param_flags_t\fP flags, void *data, size_t len)"
.br
.ti -1c
.RI "ssize_t \fBBRLAPI_STDCALL\fP \fBbrlapi__getParameter\fP (\fBbrlapi_handle_t\fP *handle, \fBbrlapi_param_t\fP parameter, \fBbrlapi_param_subparam_t\fP subparam, \fBbrlapi_param_flags_t\fP flags, void *data, size_t len)"
.br
.ti -1c
.RI "void *\fBBRLAPI_STDCALL\fP \fBbrlapi_getParameterAlloc\fP (\fBbrlapi_param_t\fP parameter, \fBbrlapi_param_subparam_t\fP subparam, \fBbrlapi_param_flags_t\fP flags, size_t *len)"
.br
.ti -1c
.RI "void *\fBBRLAPI_STDCALL\fP \fBbrlapi__getParameterAlloc\fP (\fBbrlapi_handle_t\fP *handle, \fBbrlapi_param_t\fP parameter, \fBbrlapi_param_subparam_t\fP subparam, \fBbrlapi_param_flags_t\fP flags, size_t *len)"
.br
.ti -1c
.RI "int \fBBRLAPI_STDCALL\fP \fBbrlapi_setParameter\fP (\fBbrlapi_param_t\fP parameter, \fBbrlapi_param_subparam_t\fP subparam, \fBbrlapi_param_flags_t\fP flags, const void *data, size_t len)"
.br
.ti -1c
.RI "int \fBBRLAPI_STDCALL\fP \fBbrlapi__setParameter\fP (\fBbrlapi_handle_t\fP *handle, \fBbrlapi_param_t\fP parameter, \fBbrlapi_param_subparam_t\fP subparam, \fBbrlapi_param_flags_t\fP flags, const void *data, size_t len)"
.br
.ti -1c
.RI "\fBbrlapi_paramCallbackDescriptor_t\fP \fBBRLAPI_STDCALL\fP \fBbrlapi_watchParameter\fP (\fBbrlapi_param_t\fP parameter, \fBbrlapi_param_subparam_t\fP subparam, \fBbrlapi_param_flags_t\fP flags, \fBbrlapi_paramCallback_t\fP func, void *priv, void *data, size_t len)"
.br
.ti -1c
.RI "\fBbrlapi_paramCallbackDescriptor_t\fP \fBBRLAPI_STDCALL\fP \fBbrlapi__watchParameter\fP (\fBbrlapi_handle_t\fP *handle, \fBbrlapi_param_t\fP parameter, \fBbrlapi_param_subparam_t\fP subparam, \fBbrlapi_param_flags_t\fP flags, \fBbrlapi_paramCallback_t\fP func, void *priv, void *data, size_t len)"
.br
.ti -1c
.RI "int \fBBRLAPI_STDCALL\fP \fBbrlapi_unwatchParameter\fP (\fBbrlapi_paramCallbackDescriptor_t\fP descriptor)"
.br
.ti -1c
.RI "int \fBBRLAPI_STDCALL\fP \fBbrlapi__unwatchParameter\fP (\fBbrlapi_handle_t\fP *handle, \fBbrlapi_paramCallbackDescriptor_t\fP descriptor)"
.br
.in -1c
.SH "Detailed Description"
.PP 
There are several kinds of parameters:
.IP "\(bu" 2
states associated with the braille device itself, such as its size or parameters of the device port
.IP "\(bu" 2
states of the BrlAPI connection itself, such as the displaying level or key passing preferences\&.
.IP "\(bu" 2
general states such as the cut buffer,
.IP "\(bu" 2
braille parameters: braille table, contraction, cursor shape, etc,
.IP "\(bu" 2
browse parameters: line skip, beep, etc\&.
.PP
.PP
Some of them are subdivided in subparameters\&. Others have only subparameter 0\&.
.PP
Some of them are read-only, others are read/write\&.
.PP
A client can either request the immediate content of a parameter by using \fBbrlapi_getParameter()\fP; set the content of a parameter by using \fBbrlapi_setParameter()\fP; or register a callback that may be called immediately and on each change of a given parameter, by using \fBbrlapi_watchParameter()\fP\&. 
.SH "Macro Definition Documentation"
.PP 
.SS "#define BRLAPI_PARAMF_GLOBAL   0X01"
Refer to the global value instead of the value local to the connection 
.SS "#define BRLAPI_PARAMF_LOCAL   0X00"
Refer to the value local to the connection instead of the global value 
.SS "#define BRLAPI_PARAMF_SELF   0X02"
Specify whether to receive notifications of value self-changes 
.SH "Typedef Documentation"
.PP 
.SS "typedef uint32_t \fBbrlapi_param_flags_t\fP"
Flags for parameter requests 
.SS "typedef void(* brlapi_paramCallback_t) (\fBbrlapi_param_t\fP parameter, \fBbrlapi_param_subparam_t\fP subparam, \fBbrlapi_param_flags_t\fP flags, void *priv, const void *data, size_t len)"
Callback for parameter changes
.PP
When a parameter gets changed, application-defined callbacks set by the \fBbrlapi_watchParameter()\fP function are called\&.
.PP
\fBParameters\fP
.RS 4
\fIparameter\fP is the parameter that changed; 
.br
\fIsubparam\fP is a specific instance of the parameter; 
.br
\fIflags\fP specify which value and how it was changed; 
.br
\fIpriv\fP is the void pointer that was passed to the brlapi_watchParameter call which registered the callback; 
.br
\fIdata\fP is a buffer containing the new value of the parameter; 
.br
\fIlen\fP is the size of the data\&.
.RE
.PP
This callback only gets called when the application calls some brlapi_ function (i\&.e\&. BrlAPI gets direct control of the execution)\&. 
.SS "typedef void* \fBbrlapi_paramCallbackDescriptor_t\fP"
Type for callback descriptors This is returned by brlapi_watchParameter, to be passed to brlapi_unwatchParameter\&. 
.SH "Enumeration Type Documentation"
.PP 
.SS "enum \fBbrlapi_param_t\fP"

.PP
\fBEnumerator\fP
.in +1c
.TP
\fB\fIBRLAPI_PARAM_SERVER_VERSION \fP\fP
Version of the server: uint32_t 
.TP
\fB\fIBRLAPI_PARAM_CLIENT_PRIORITY \fP\fP
Priority of the client: uint32_t (from 0 through 100, default is 50) 
.TP
\fB\fIBRLAPI_PARAM_DRIVER_NAME \fP\fP
Full name of the driver: string 
.TP
\fB\fIBRLAPI_PARAM_DRIVER_CODE \fP\fP
Code (short name) of the driver: string 
.TP
\fB\fIBRLAPI_PARAM_DRIVER_VERSION \fP\fP
Version of the driver: string 
.TP
\fB\fIBRLAPI_PARAM_DEVICE_MODEL \fP\fP
Model of the device: string 
.TP
\fB\fIBRLAPI_PARAM_DEVICE_CELL_SIZE \fP\fP
Number of dots in a cell: uint8_t 
.TP
\fB\fIBRLAPI_PARAM_DISPLAY_SIZE \fP\fP
Dimensions of the braille display: { uint32_t columns; uint32_t rows; } 
.TP
\fB\fIBRLAPI_PARAM_DEVICE_IDENTIFIER \fP\fP
Identifier of the device: string 
.TP
\fB\fIBRLAPI_PARAM_DEVICE_SPEED \fP\fP
Speed of the device: uint32_t 
.TP
\fB\fIBRLAPI_PARAM_DEVICE_ONLINE \fP\fP
Device is online: boolean 
.TP
\fB\fIBRLAPI_PARAM_RETAIN_DOTS \fP\fP
Pass dot combinations (rather than characters): boolean 
.TP
\fB\fIBRLAPI_PARAM_COMPUTER_BRAILLE_CELL_SIZE \fP\fP
Number of dots used to render a computer braille character: uint8_t (8 or 6) 
.TP
\fB\fIBRLAPI_PARAM_LITERARY_BRAILLE \fP\fP
Whether braille is literary (rather than computer): boolean 
.TP
\fB\fIBRLAPI_PARAM_CURSOR_DOTS \fP\fP
Representation of the cursor: uint8_t (ISO 11548-1) 
.TP
\fB\fIBRLAPI_PARAM_CURSOR_BLINK_PERIOD \fP\fP
Blinking period of the cursor: uint32_t (milliseconds) 
.TP
\fB\fIBRLAPI_PARAM_CURSOR_BLINK_PERCENTAGE \fP\fP
Portion of the blinking period that the cursor is visible: uint8_t (from 0 through 100) 
.TP
\fB\fIBRLAPI_PARAM_RENDERED_CELLS \fP\fP
Cells rendered by the client: uint8_t[] (ISO 11548-1), one cell per element 
.TP
\fB\fIBRLAPI_PARAM_SKIP_IDENTICAL_LINES \fP\fP
Whether to skip identical screen lines: boolean 
.TP
\fB\fIBRLAPI_PARAM_AUDIBLE_ALERTS \fP\fP
Whether to use audible alerts: boolean 
.TP
\fB\fIBRLAPI_PARAM_CLIPBOARD_CONTENT \fP\fP
Content of the clipboard: UTF-8 string 
.TP
\fB\fIBRLAPI_PARAM_BOUND_COMMAND_KEYCODES \fP\fP
Commands bound by the driver: uint64_t[], one command keycode per element 
.TP
\fB\fIBRLAPI_PARAM_COMMAND_KEYCODE_NAME \fP\fP
Name for a command keycode (specified via the subparam argument): string (usually a few characters) 
.TP
\fB\fIBRLAPI_PARAM_COMMAND_KEYCODE_SUMMARY \fP\fP
Description for a command keycode (specified via the subparam argument): string (usually a few words) 
.TP
\fB\fIBRLAPI_PARAM_DEFINED_DRIVER_KEYCODES \fP\fP
Keycodes defined by the driver: uint64_t[], one keycode per element 
.TP
\fB\fIBRLAPI_PARAM_DRIVER_KEYCODE_NAME \fP\fP
Name for a driver keycode (specified via the subparam argument): string (usually a few characters) 
.TP
\fB\fIBRLAPI_PARAM_DRIVER_KEYCODE_SUMMARY \fP\fP
Description for a driver keycode (specified via the subparam argument): string (usually a few words) 
.TP
\fB\fIBRLAPI_PARAM_COMPUTER_BRAILLE_ROWS_MASK \fP\fP
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 
.TP
\fB\fIBRLAPI_PARAM_COMPUTER_BRAILLE_ROW_CELLS \fP\fP
Computer braille cells for a Unicode row (specified via the subparam argument): uint8_t[256] (ISO 11548-1), one cell per element 
.TP
\fB\fIBRLAPI_PARAM_COMPUTER_BRAILLE_TABLE \fP\fP
Name of the computer braille table: string 
.TP
\fB\fIBRLAPI_PARAM_LITERARY_BRAILLE_TABLE \fP\fP
Name of the literary braille table: string 
.TP
\fB\fIBRLAPI_PARAM_MESSAGE_LOCALE \fP\fP
Locale to use for messages: string 
.TP
\fB\fIBRLAPI_PARAM_DRIVER_PROPERTY_VALUE \fP\fP
Value of a driver-specific property: uint32_t 
.TP
\fB\fIBRLAPI_PARAM_COUNT \fP\fP
.SH "Function Documentation"
.PP 
.SS "ssize_t \fBBRLAPI_STDCALL\fP brlapi__getParameter (\fBbrlapi_handle_t\fP * handle, \fBbrlapi_param_t\fP parameter, \fBbrlapi_param_subparam_t\fP subparam, \fBbrlapi_param_flags_t\fP flags, void * data, size_t len)"

.SS "void *\fBBRLAPI_STDCALL\fP brlapi__getParameterAlloc (\fBbrlapi_handle_t\fP * handle, \fBbrlapi_param_t\fP parameter, \fBbrlapi_param_subparam_t\fP subparam, \fBbrlapi_param_flags_t\fP flags, size_t * len)"

.SS "int \fBBRLAPI_STDCALL\fP brlapi__setParameter (\fBbrlapi_handle_t\fP * handle, \fBbrlapi_param_t\fP parameter, \fBbrlapi_param_subparam_t\fP subparam, \fBbrlapi_param_flags_t\fP flags, const void * data, size_t len)"

.SS "int \fBBRLAPI_STDCALL\fP brlapi__unwatchParameter (\fBbrlapi_handle_t\fP * handle, \fBbrlapi_paramCallbackDescriptor_t\fP descriptor)"

.SS "\fBbrlapi_paramCallbackDescriptor_t\fP \fBBRLAPI_STDCALL\fP brlapi__watchParameter (\fBbrlapi_handle_t\fP * handle, \fBbrlapi_param_t\fP parameter, \fBbrlapi_param_subparam_t\fP subparam, \fBbrlapi_param_flags_t\fP flags, \fBbrlapi_paramCallback_t\fP func, void * priv, void * data, size_t len)"

.SS "ssize_t \fBBRLAPI_STDCALL\fP brlapi_getParameter (\fBbrlapi_param_t\fP parameter, \fBbrlapi_param_subparam_t\fP subparam, \fBbrlapi_param_flags_t\fP flags, void * data, size_t len)"
Get the content of a parameter
.PP
brlapi_getParameter gets the current content of a parameter
.PP
\fBParameters\fP
.RS 4
\fIparameter\fP is the parameter whose content shall be gotten; 
.br
\fIsubparam\fP is a specific instance of the parameter; 
.br
\fIflags\fP specify which value and how it should be returned; 
.br
\fIdata\fP is a buffer where content of the parameter shall be stored; 
.br
\fIlen\fP is the size of the buffer\&.
.RE
.PP
\fBReturns\fP
.RS 4
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\&. 
.RE
.PP

.SS "void *\fBBRLAPI_STDCALL\fP brlapi_getParameterAlloc (\fBbrlapi_param_t\fP parameter, \fBbrlapi_param_subparam_t\fP subparam, \fBbrlapi_param_flags_t\fP flags, size_t * len)"
Return the content of a parameter
.PP
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\&.
.PP
\fBParameters\fP
.RS 4
\fIparameter\fP is the parameter whose content shall be gotten; 
.br
\fIsubparam\fP is a specific instance of the parameter; 
.br
\fIflags\fP specify which value and how it should be returned; 
.br
\fIlen\fP is the address where to store the size of the parameter value\&.
.RE
.PP
\fBReturns\fP
.RS 4
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 
.RE
.PP

.SS "int \fBBRLAPI_STDCALL\fP brlapi_setParameter (\fBbrlapi_param_t\fP parameter, \fBbrlapi_param_subparam_t\fP subparam, \fBbrlapi_param_flags_t\fP flags, const void * data, size_t len)"
Set the content of a parameter
.PP
brlapi_setParameter sets the content of a parameter
.PP
\fBParameters\fP
.RS 4
\fIparameter\fP is the parameter to set; 
.br
\fIsubparam\fP is a specific instance of the parameter; 
.br
\fIflags\fP specify which value and how it should be set; 
.br
\fIdata\fP is a buffer containing the data to store in the parameter; 
.br
\fIlen\fP is the size of the data\&.
.RE
.PP
\fBReturns\fP
.RS 4
0 on success, -1 on error (read-only parameter for instance)\&. 
.RE
.PP

.SS "int \fBBRLAPI_STDCALL\fP brlapi_unwatchParameter (\fBbrlapi_paramCallbackDescriptor_t\fP descriptor)"
Clear a parameter change callback
.PP
brlapi_unwatchParameter unregisters a parameter change callback: the callback function previously registered with brlapi_watchParameter will not be called any longer\&.
.PP
\fBParameters\fP
.RS 4
\fIdescriptor\fP refers to the callback to be removed\&.
.RE
.PP
\fBReturns\fP
.RS 4
0 on success, -1 on error\&. 
.RE
.PP

.SS "\fBbrlapi_paramCallbackDescriptor_t\fP \fBBRLAPI_STDCALL\fP brlapi_watchParameter (\fBbrlapi_param_t\fP parameter, \fBbrlapi_param_subparam_t\fP subparam, \fBbrlapi_param_flags_t\fP flags, \fBbrlapi_paramCallback_t\fP func, void * priv, void * data, size_t len)"
Set a parameter change callback
.PP
brlapi_watchParameter registers a parameter change callback: whenever the given parameter changes, the given function is called\&.
.PP
\fBParameters\fP
.RS 4
\fIparameter\fP is the parameter to watch; 
.br
\fIsubparam\fP is a specific instance of the parameter; 
.br
\fIflags\fP specify which value and how it should be monitored; 
.br
\fIfunc\fP is the function to call on parameter change; 
.br
\fIpriv\fP is a void pointer which will be passed as such to the function; 
.br
\fIdata\fP is a buffer where the current content of the parameter shall be stored; 
.br
\fIlen\fP is the size of the buffer\&.
.RE
.PP
\fBReturns\fP
.RS 4
the callback descriptor (to be passed to brlapi_unwatchParameter to unregister the callback), or NULL on error\&.
.RE
.PP
\fBNote\fP
.RS 4
Default parameter callbacks don't do anything, except the ones for display size which just raise SIGWINCH\&. 
.PP
If data is NULL, the callback will be called immediately by brlapi_watchParameter, for providing the initial value 
.RE
.PP

.SH "Author"
.PP 
Generated automatically by Doxygen for BrlAPI from the source code\&.