Gets the value that is stored at @key in @settings, subject to
application-level validation/mapping.
You should use this function when the application needs to perform
some processing on the value of the key (for example, parsing). The
@mapping function performs that processing. If the function
indicates that the processing was unsuccessful (due to a parse error,
for example) then the mapping is tried again with another value.
This allows a robust 'fall back to defaults' behaviour to be
implemented somewhat automatically.
The first value that is tried is the user's setting for the key. If
the mapping function fails to map this value, other values may be
tried in an unspecified order (system or site defaults, translated
schema default values, untranslated schema default values, etc).
If the mapping function fails for all possible values, one additional
attempt is made: the mapping function is called with a %NULL value.
If the mapping function still indicates failure at this point then
the application will be aborted.
The result parameter for the @mapping function is pointed to a
#gpointer which is initially set to %NULL. The same pointer is given
to each invocation of @mapping. The final value of that #gpointer is
what is returned by this function. %NULL is valid; it is returned
just as any other value would be.
Gets the value that is stored at @key in @settings, subject to application-level validation/mapping.
You should use this function when the application needs to perform some processing on the value of the key (for example, parsing). The @mapping function performs that processing. If the function indicates that the processing was unsuccessful (due to a parse error, for example) then the mapping is tried again with another value.
This allows a robust 'fall back to defaults' behaviour to be implemented somewhat automatically.
The first value that is tried is the user's setting for the key. If the mapping function fails to map this value, other values may be tried in an unspecified order (system or site defaults, translated schema default values, untranslated schema default values, etc).
If the mapping function fails for all possible values, one additional attempt is made: the mapping function is called with a %NULL value. If the mapping function still indicates failure at this point then the application will be aborted.
The result parameter for the @mapping function is pointed to a #gpointer which is initially set to %NULL. The same pointer is given to each invocation of @mapping. The final value of that #gpointer is what is returned by this function. %NULL is valid; it is returned just as any other value would be.