A plug-in runtime defines a static instance of this structure to pass information to the plug-in framework. The plug-in framework then uses the information to create and control plug-in instances. The symbol pointing to the runtime information instance is named by the funcs attribute of the runtime element in a plug-in descriptor.
The following graph displays how these functions are used to control the state of the plug-in instance.
Data Fields | |
| void *(* | create )(cp_context_t *ctx) |
| An initialization function called to create a new plug-in runtime instance. | |
| int(* | start )(void *data) |
| A start function called to start a plug-in instance. | |
| void(* | stop )(void *data) |
| A stop function called to stop a plugin instance. | |
| void(* | destroy )(void *data) |
| A destroy function called to destroy a plug-in instance. | |
| void*(* create)(cp_context_t *ctx) |
An initialization function called to create a new plug-in runtime instance.
The initialization function initializes and returns an opaque plug-in instance data pointer which is then passed on to other control functions. This data pointer should be used to access plug-in instance specific data. For example, the context reference must be stored as part of plug-in instance data if the plug-in runtime needs it. On failure, the function must return NULL.
C-pluff API functions must not be called from within a create function invocation and symbols from imported plug-ins must not be used because they may not available yet.
| ctx | the plug-in context of the new plug-in instance |
| int(* start)(void *data) |
A start function called to start a plug-in instance.
The start function must return zero (CP_OK) on success and non-zero on failure. If the start fails then the stop function (if any) is called to clean up plug-in state. Library initialization, plug-in context management and plug-in management functions must not be called from within a start function invocation. The start function pointer can be NULL if the plug-in runtime does not have a start function.
The start function implementation should set up plug-in and return promptly. If there is further work to be done then a plug-in can start a thread or register a run function using cp_run_function. Symbols from imported plug-ins are guaranteed to be available for the start function.
| data | an opaque pointer to plug-in instance data |
| void(* stop)(void *data) |
A stop function called to stop a plugin instance.
This function must cease all plug-in runtime activities. Library initialization, plug-in context management, plug-in management functions, cp_run_function and cp_resolve_symbol must not be called from within a stop function invocation. The stop function pointer can be NULL if the plug-in runtime does not have a stop function. It is guaranteed that no run functions registered by the plug-in are called simultaneously or after the call to the stop function.
The stop function should release any external resources hold by the plug-in. Dynamically resolved symbols are automatically released and dynamically defined symbols and registered run functions are automatically unregistered after the call to stop function. Resolved external symbols are still available for the stop function and symbols provided by the plug-in should remain available after the call to stop function (although functionality might be limited). Final cleanup can be safely done in the destroy function.
| data | an opaque pointer to plug-in instance data |
| void(* destroy)(void *data) |
A destroy function called to destroy a plug-in instance.
This function should release any plug-in instance data. The plug-in is stopped before this function is called. C-Pluff API functions must not be called from within a destroy function invocation and symbols from imported plug-ins must not be used because they may not be available anymore. Correspondingly, it is guaranteed that the symbols provided by the plug-in are not used by other plug-ins when destroy function has been called.
| data | an opaque pointer to plug-in instance data |
Generated on Fri Apr 6 15:40:57 2007 for C-Pluff C API by 
1.5.1