[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