[sldev] Plugin API
Argent Stonecutter
secret.argent at gmail.com
Thu Feb 22 06:50:17 PST 2007
[also in the discussion section on the wiki]
I don't like the idea of anonymous pointers for parameter passing. I
think that some kind of parameter list is essential.
typedef struct {
int sl_param_id; // Defined in the particular function's API
enum {
SL_INT32, SL_INT64, SL_FLOAT32, SL_FLOAT64, SL_STRING,
SL_ALLOCED_STRING, ...
} sl_type; // Plugin may ignore parameters
int sl_required; // If set, plugin MUST handle this parameter
int sl_changed; // Zero before any plugin called, non-zero if
any plugin has changed it
int64_t sl_value; // If the type is only 32 bits long, high 32
bits must be zero.
} sl_param;
typedef enum { SL_OK, SL_INCOMPATIBLE, SL_ERROR, SL_BREAK } sl_result;
sl_result sl_plugin(int count, sl_param params[], sl_param *error_info);
The function calling the plugin can have all these set in a static
structure, and only needs to zero out the sl_changed parameters and
set up the initial values. Plugins do not call plugins, the list of
plugins for the function are called sequentially by the
sl_handle_plugins routine.
if(my_plugins != NULL) {
my_params[0].sl_changed = 0;
my_params[0].sl_value = whatever;
final_result = sl_handle_plugins(my_plugins, 1, my_params,
&error_param);
if(final_result == SL_BREAK) return success;
if(final_result == SL_ERROR) {
panic(error_param);
return failure;
}
}
The plugin must at a minimum:
* verify that the sl_param_id values are what it expects and
handle (even if by ignoring) the wrong values
* handle (even if by ignoring the parameter) the "wrong" types
* return SL_INCOMPATIBLE if any of the parameters it's ignoring
have sl_required set.
* set sl_changed for any parameters it's changed
* fill in error_info if it returns SL_ERROR
* free an SL_ALLOCED_STRING if it changes the string
* make sure that the type of a string parameter is
SL_ALLOCED_STRING or SL_STRING to let the caller or later plugins
know how to deal with them
The plugin may:
* Handle changes to the order of parameters as indicated by
sl_param_id
* Handle changes to the types of parameters as indicated by sl_type
* Behave differently if a previous plugin has changed a parameter
Return values:
* SL_OK - Normal return, go on to the next plugin
* SL_INCOMPATIBLE - This plugin no longer works with this call.
Let the user know and don't call this plugin again.
* SL_ERROR - This plugin has detected an error sufficiently
severe that this call must abort. Should be rare.
o error_info must be set to { original_param_id, SL_STRING
or SL_ALLOCED_STRING, TRUE, TRUE, error_message }.
* SL_BREAK - Don't call any further plugins, don't run the rest
of the function, the plugin has completely handled the call.
More information about the SLDev
mailing list