User manual

102
device defined configuration options. Both ways are described below but the new one is
preferable.
4.20.1 The legacy way of changing the configuration
The legacy way of changing the configuration belongs to the class of operations called
“Request for changing the configuration”. The CHARON core initiates such an operation
when loading the configuration. The CHAPI defines the additional configuration option
parameters, and passes the device specific configuration information to the device instance
as indicated by the following example:
load chapi <CFG-NAME>
set <CFG-NAME> dll=<PATH-TO-DLL> parameters=”…”
To perform the operation, the initiator invokes a routine identified by the set_configuration
field of the chapi_out descriptor. The initiator provides in the parameters argument a
character string, as specified in the configuration for the parameters option. The procedure
is invoked as follows:
const chapi_out * co = …;
if (co->set_configuration) {
co->set_configuration(co, parameters);
}
The example above shows that the device is not obliged to support the indicated
operation.
4.20.2 The recommended way of changing the configuration
The recommended way of changing the configuration belongs to the class of operations
called “Request for changing the configuration”. The CHARON core initiates such an
operation when loading the configuration. A loadable device can define its required
configuration options during the initialization cycle (see section 4.19 for details and
examples). These options become available in configuration file after that cycle and
provide a more convenient way to configure a loadable device. There is a restriction how
these options should be specified in configuration file: they have to be specified in after dll
configuration option specification and not on the same line of the dll specification.
Assuming that a loadable component has defined three options as described above –
int_opt, bool_opt and str_opt. It would be configured as follows:
load chapi <CFG-NAME>
// our options are not visible at the line below
set <CFG-NAME> dll=<PATH-TO-DLL>
// … but visible at the next line and any other one in configuration file
set <CFG-NAME> int_opt=<INTEGER_NUMBER> str_opt=<STRING_CONSTANT>
set <CFG-NAME> bool_opt[x]=<false|true>
To perform the operation, the initiator invokes a routine identified by the
set_configuration_ex field of the chapi_out descriptor. This call notifies a loadable component