Synopsis:
#include <aoi.h>
int32_t (*VerifyValue)(AOResource_t *setting, const void *newvalue);
Arguments:
- setting
- A pointer to an AOResource_t structure containing an entry read from
the Settings array.
- newvalue
- A pointer to the value for the setting as read from the configuration file. For details on how configuration settings are stored
in the file, see the aoiconftool entry in the Utilities Reference.
Description:
This function's purpose is to give the addon a value setting that was read from the configuration file and let it check that the value is
acceptable. The library calls this function for individual settings in the same order as they're listed in the Settings
array, and calls it only if the configuration file value is different from the default value in this array.
When your VerifyValue() function is called, setting->value points to your
default value and newvalue points to the value read from the configuration file.
This allows you to determine if the configuration file value is acceptable;
for example, you can check the syntax of a string or whether a numeric value is within a certain range.
At this point, you don't know the values of all other settings, so you can't verify this value setting in their context.
You can do that later through VerifyAll().
While you could also verify all individual values in this other function, the VerifyValue() function lets you optimize
the checking of individual values.
Whenever
VerifyValue() returns zero to indicate that the new value has been accepted, the library then makes
setting->
value point to this new value. There are two ways of doing this:
- When setting->value points to a fixed-sized area of memory, the library copies the new value
into that memory, overwriting the default value. This applies to all scalars (i.e., all numeric types and TOGGLE;
see Settings for details), and to strings
when a buffer size was provided via setting->info.
Note that the buffer size imposes a length limit for strings—if the configuration file value is longer than this limit,
it's considered invalid, causing your addon's initialization to fail. If you don't want a limit, use the scheme described in the
next paragraph.
- When the type is AOR_TYPE_STRING and setting->info is NULL, this implies that
the default value that setting->value points to should not be overwritten. In this case, the
library changes settings->value to point to a new memory location that holds the new value.
Note that for this to work, your Settings array must be located in writable memory (i.e., not declared
const).
Returns:
Zero if the value setting is accepted, non-zero if it's rejected
(which will cause the initialization of the addon to fail and the library to unload the DLL).