.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_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\&.