The basic plugin interface definition.
More...
|
cpl_error_code | cpl_plugin_copy (cpl_plugin *self, const cpl_plugin *other) |
| Copy a plugin.
|
|
void | cpl_plugin_delete (cpl_plugin *self) |
| Destroy a plugin.
|
|
void | cpl_plugin_dump (const cpl_plugin *self, FILE *stream) |
| Dump the plugin debugging information to the given stream.
|
|
unsigned int | cpl_plugin_get_api (const cpl_plugin *self) |
| Get the version number of the plugin interface implementation.
|
|
const char * | cpl_plugin_get_author (const cpl_plugin *self) |
| Get the name of the plugin author.
|
|
const char * | cpl_plugin_get_copyright (const cpl_plugin *self) |
| Get the license and copyright information of a plugin.
|
|
cpl_plugin_func | cpl_plugin_get_deinit (const cpl_plugin *self) |
| Get the cleanup handler of a plugin.
|
|
const char * | cpl_plugin_get_description (const cpl_plugin *self) |
| Get the detailed description of a plugin.
|
|
const char * | cpl_plugin_get_email (const cpl_plugin *self) |
| Get the contact information of a plugin.
|
|
cpl_plugin_func | cpl_plugin_get_exec (const cpl_plugin *self) |
| Get the execution handler of a plugin.
|
|
int | cpl_plugin_get_info (cpl_pluginlist *cpl_plugin_list) |
| Append the plugin information to the given list.
|
|
cpl_plugin_func | cpl_plugin_get_init (const cpl_plugin *self) |
| Get the initialisation handler of a plugin.
|
|
const char * | cpl_plugin_get_name (const cpl_plugin *self) |
| Get the name of a plugin.
|
|
const char * | cpl_plugin_get_synopsis (const cpl_plugin *self) |
| Get the short description of a plugin.
|
|
unsigned long | cpl_plugin_get_type (const cpl_plugin *self) |
| Get the type of a plugin.
|
|
char * | cpl_plugin_get_type_string (const cpl_plugin *self) |
| Get the type of a plugin as string.
|
|
unsigned long | cpl_plugin_get_version (const cpl_plugin *self) |
| Get the version number of a plugin.
|
|
char * | cpl_plugin_get_version_string (const cpl_plugin *self) |
| Get the version number of a plugin as a string.
|
|
cpl_error_code | cpl_plugin_init (cpl_plugin *self, unsigned int api, unsigned long version, unsigned long type, const char *name, const char *synopsis, const char *description, const char *author, const char *email, const char *copyright, cpl_plugin_func create, cpl_plugin_func execute, cpl_plugin_func destroy) |
| Initialise a plugin.
|
|
cpl_plugin * | cpl_plugin_new (void) |
| Create a new, empty plugin interface.
|
|
cpl_error_code | cpl_plugin_set_api (cpl_plugin *self, unsigned int api) |
| Set the plugin interface version number.
|
|
cpl_error_code | cpl_plugin_set_author (cpl_plugin *self, const char *author) |
| Set the name of the plugin author.
|
|
cpl_error_code | cpl_plugin_set_copyright (cpl_plugin *self, const char *copyright) |
| Set the license and copyright information of a plugin.
|
|
cpl_error_code | cpl_plugin_set_deinit (cpl_plugin *self, cpl_plugin_func func) |
| Set the cleanup handler of a plugin.
|
|
cpl_error_code | cpl_plugin_set_description (cpl_plugin *self, const char *description) |
| Set the detailed description of a plugin.
|
|
cpl_error_code | cpl_plugin_set_email (cpl_plugin *self, const char *email) |
| Set the contact information of a plugin.
|
|
cpl_error_code | cpl_plugin_set_exec (cpl_plugin *self, cpl_plugin_func func) |
| Set the execution handler of a plugin.
|
|
cpl_error_code | cpl_plugin_set_init (cpl_plugin *self, cpl_plugin_func func) |
| Set the initialisation handler of a plugin.
|
|
cpl_error_code | cpl_plugin_set_name (cpl_plugin *self, const char *name) |
| Set the name of a plugin.
|
|
cpl_error_code | cpl_plugin_set_synopsis (cpl_plugin *self, const char *synopsis) |
| Set the short description of a plugin.
|
|
cpl_error_code | cpl_plugin_set_type (cpl_plugin *self, unsigned long type) |
| Set the type of a plugin.
|
|
int | cpl_plugin_set_version (cpl_plugin *self, unsigned long version) |
| Set the version number of a plugin.
|
|
The basic plugin interface definition.
This module defines the basic plugin interface. The plugin interface provides the possibility to dynamically load and execute software modules. The basic plugin interface defined here serves as `superclass' for context specific plugins. All context specific plugins inherit this basic plugin interface. A plugin context is represented by a type code, i.e. the different plugin contexts are represented as different plugin types.
Most of the time an application using the plugin interface is dealing only with this basic, plugin type independent part of the interface. It provides the application with the necessary information about a particular plugin implementation and the services to initialise, execute and cleanup a dynamically loaded module.
In this way plugin type specific details may remain hidden from the application until the plugin type and its implementation details are known through querying the basic plugin interface part.
To obtain a filled plugin interface structure the application will call the function cpl_plugin_get_info()
, which has the following prototype:
#include <cpl_pluginlist.h>
For each plugin library (a shared object library containing one or more plugins) this function must be implemented by the plugin developer. Its purpose is to fill a plugin interface structure for each plugin the plugin library contains and add it to a list provided by the application. This list of plugin interfaces provides the application with all the details on how to communicate with a particular plugin.
As an example on how to create a context specific plugin, i.e. how to create a new plugin type, you may have a look at Recipes.
- Synopsis:
-
The plugin data type.
This defines the (public) plugin data type.
Data type used to store the plugin type code.
Definition of plugin types.
Predefined plugin types supported by the Common Pipeline Library itself.
- Enumerator:
CPL_PLUGIN_TYPE_NONE |
Plugin is of unknown or undefined type
|
CPL_PLUGIN_TYPE_RECIPE |
Plugin is a complete data reduction task, i.e. a sequence of individual data reduction steps, turning a raw frame into a `final' product.
|
CPL_PLUGIN_TYPE_RECIPE_V2 |
Plugin is a recipe, i.e. a complete data reduction task. In addition, this recipe version provides extra data about the required input data. This plugin is a subclass of CPL_PLUGIN_TYPE_RECIPE .
|
Copy a plugin.
- Parameters
-
self | A plugin. |
other | The plugin structure to copy. |
- Returns
- The function returns
CPL_ERROR_NONE
on success or a CPL error code otherwise.
- Errors
CPL_ERROR_NULL_INPUT | The parameter self or other is a NULL pointer. |
The function copies all members of the plugin other to the plugin self. The plugin other and its copy self do not share any resources after the copy operation. If either self, or other are invalid pointers, the function returns immediately.
Note that the plugins self and other do not need to be of the same kind (see below).
- Attention
- If a derived plugin (a
cpl_recipe
for instance) is passed to this function, after casting it to its base, a cpl_plugin
this function most likely will not work as expected, since data slicing will happen. The function is only aware of the cpl_plugin
part of the derived plugin and only these data members are copied. Any additional data members defined by the derived plugin are therefore lost, unless they are copied explicitly.
The should be used function as follows. If necessary, create the target plugin using the appropriate constructor, or allocate a memory block of the appropriate size to hold the derived plugin type. Use this function to copy the cpl_plugin
part of your derived plugin. Copy additional data members of the target plugin explicitely.
Destroy a plugin.
- Parameters
-
self | The plugin to destroy. |
- Returns
- Nothing.
The function destroys a plugin. First, the memory used by the members of the cpl_plugin
type is released and then the plugin itself is destroyed.
- Attention
- The function may also be used to destroy plugins which have been derived from the
cpl_plugin
type. But if the derived plugin type defines members which are dynamically allocated, they have to be destroyed explicitly before (in the plugin's cleanup handler for instance) the derived plugin is passed to this function, or the references to these memory blocks have to be kept and cleaned up later. Otherwise memory leaks may result. If the plugin self is NULL
, nothing is done and no error is set.
void cpl_plugin_dump |
( |
const cpl_plugin * |
self, |
|
|
FILE * |
stream |
|
) |
| |
Dump the plugin debugging information to the given stream.
- Parameters
-
self | The plugin. |
stream | The output stream to use. |
- Returns
- Nothing.
The function dumps the contents of of the plugin self to the output stream stream. If stream is NULL
the function writes to the standard output. If self is NULL
the function does nothing.
unsigned int cpl_plugin_get_api |
( |
const cpl_plugin * |
self | ) |
|
Get the version number of the plugin interface implementation.
- Parameters
-
- Returns
- The version number of the plugin interface implementation the plugin self complies with. If an error occurs the function returns 0 and sets an appropriate error code.
- Errors
CPL_ERROR_NULL_INPUT | The parameter self is a NULL pointer. |
This function returns the plugin interface version number, i.e. the version number describing the layout of the plugin data type itself. Valid version numbers are always greater or equal to 1.
const char* cpl_plugin_get_author |
( |
const cpl_plugin * |
self | ) |
|
Get the name of the plugin author.
- Parameters
-
- Returns
- The function returns a pointer to the plugin author's name string. If an error occurs the function returns
NULL
and sets an appropriate error code.
- Errors
CPL_ERROR_NULL_INPUT | The parameter self is a NULL pointer. |
This function returns a reference to the name of the author of the plugin self. The plugin author's name must not be modified using the returned pointer. The appropriate method should be used instead!
const char* cpl_plugin_get_copyright |
( |
const cpl_plugin * |
self | ) |
|
Get the license and copyright information of a plugin.
- Parameters
-
- Returns
- The function returns a pointer to the plugin's copyright information string. If an error occurs the function returns
NULL
and sets an appropriate error code.
- Errors
CPL_ERROR_NULL_INPUT | The parameter self is a NULL pointer. |
This function returns a reference to the license and copyright information of the plugin self. The copyright information must not be modified using the returned pointer. The appropriate method should be used instead!
cpl_plugin_func cpl_plugin_get_deinit |
( |
const cpl_plugin * |
self | ) |
|
Get the cleanup handler of a plugin.
- Parameters
-
- Returns
- The plugin's cleanup handler. If an error occurs the function returns
NULL
and sets an appropriate error code.
- Errors
CPL_ERROR_NULL_INPUT | The parameter self is a NULL pointer. |
The function returns the cleanup handler of the plugin self.
const char* cpl_plugin_get_description |
( |
const cpl_plugin * |
self | ) |
|
Get the detailed description of a plugin.
- Parameters
-
- Returns
- The function returns a pointer to the plugin's detailed description. If an error occurs the function returns
NULL
and sets an appropriate error code.
- Errors
CPL_ERROR_NULL_INPUT | The parameter self is a NULL pointer. |
This function returns a reference to the detailed description (a description of the algorithm for instance) of the plugin self. The plugin's description must not be modified using this pointer. Use the appropriate method instead!
const char* cpl_plugin_get_email |
( |
const cpl_plugin * |
self | ) |
|
Get the contact information of a plugin.
- Parameters
-
- Returns
- The function returns a pointer to the plugin author's contact information string. If an error occurs the function returns
NULL
and sets an appropriate error code.
- Errors
CPL_ERROR_NULL_INPUT | The parameter self is a NULL pointer. |
This function returns a reference to the e-mail address of the author of the plugin self. The plugin author's e-mail address must not be modified using the returned pointer. The appropriate method should be used instead!
cpl_plugin_func cpl_plugin_get_exec |
( |
const cpl_plugin * |
self | ) |
|
Get the execution handler of a plugin.
- Parameters
-
- Returns
- The plugin's execution function. If an error occurs the function returns
NULL
and sets an appropriate error code.
- Errors
CPL_ERROR_NULL_INPUT | The parameter self is a NULL pointer. |
The function returns the execution function of the plugin self.
Append the plugin information to the given list.
- Parameters
-
cpl_plugin_list | A plugin list. |
- Returns
- The function must return 0 on success and 1 in case of an error.
This function must be implemented by plugin developers. There must be one such implementation per plugin library, regardless of how many plugins the library actually offers, provided that there is at least one plugin implemented in this library.
This prototype is only provided in order to allow the compiler to do some basic checks when compiling a plugin library. To have the prototype available when you are compiling your plugin library, you must add the line
#include <cpl_plugininfo.h>
to your plugin source file.
The purpose of this function is to create a plugin object for each plugin implementation provided by the plugin library, fill the basic plugin interface (the cpl_plugin
part of the created plugin object) and append the created object to the plugin list list.
The list will be provided by the application which is going to use the plugin and it may be expected that list points to a valid plugin list when this function is called.
cpl_plugin_func cpl_plugin_get_init |
( |
const cpl_plugin * |
self | ) |
|
Get the initialisation handler of a plugin.
- Parameters
-
- Returns
- The plugin's initalization function. If an error occurs the function returns
NULL
and sets an appropriate error code.
- Errors
CPL_ERROR_NULL_INPUT | The parameter self is a NULL pointer. |
The function returns the initalisation function of the plugin self.
const char* cpl_plugin_get_name |
( |
const cpl_plugin * |
self | ) |
|
Get the name of a plugin.
- Parameters
-
- Returns
- The function returns a pointer to the plugin's unique name string. If an error occurs the function returns
NULL
and sets an appropriate error code.
- Errors
CPL_ERROR_NULL_INPUT | The parameter self is a NULL pointer. |
This function returns a reference to the unique name of the plugin self. The plugin's name must not be modified using the returned pointer. The appropriate method should be used instead.
const char* cpl_plugin_get_synopsis |
( |
const cpl_plugin * |
self | ) |
|
Get the short description of a plugin.
- Parameters
-
- Returns
- The function returns a pointer to the plugin's short description. If an error occurs the function returns
NULL
and sets an appropriate error code.
- Errors
CPL_ERROR_NULL_INPUT | The parameter self is a NULL pointer. |
This function returns a reference to the short description (its purpose for instance) of the plugin self. The plugin's short description must not be modified using this pointer. Use the appropriate method instead!
unsigned long cpl_plugin_get_type |
( |
const cpl_plugin * |
self | ) |
|
Get the type of a plugin.
- Parameters
-
- Returns
- The function returns the plugin type code. If an error occurs the function returns CPL_PLUGIN_TYPE_NONE and sets an appropriate error code.
- Errors
CPL_ERROR_NULL_INPUT | The parameter self is a NULL pointer. |
This function returns the type (cf. cpl_plugin_type) of the plugin self.
char* cpl_plugin_get_type_string |
( |
const cpl_plugin * |
self | ) |
|
Get the type of a plugin as string.
- Parameters
-
- Returns
- The function returns the string representation of the plugin type. If an error occurs the function returns
NULL
and sets an appropriate error code.
- Errors
CPL_ERROR_NULL_INPUT | The parameter self is a NULL pointer. |
This function returns the plugin type of self as a string. The type string is placed into a newly allocated buffer. This buffer must be deallocated using cpl_free() by the caller if it is no longer needed.
unsigned long cpl_plugin_get_version |
( |
const cpl_plugin * |
self | ) |
|
Get the version number of a plugin.
- Parameters
-
- Returns
- The plugin's version number. If an error occurs the function returns 0 and sets an appropriate error code.
- Errors
CPL_ERROR_NULL_INPUT | The parameter self is a NULL pointer. |
This function returns the version number of the plugin self.
char* cpl_plugin_get_version_string |
( |
const cpl_plugin * |
self | ) |
|
Get the version number of a plugin as a string.
- Parameters
-
- Returns
- The string representation of the plugin's version number. If an error occurs the function returns
NULL
and sets an appropriate error code.
- Errors
CPL_ERROR_NULL_INPUT | The parameter self is a NULL pointer. |
This function returns the version number of the plugin self as a string. The function assumes that the integer representation of the plugin version can be decoded into a version string of the usual form: "major.minor.micro"
The resulting string is placed in a newly allocated buffer. This buffer must be deallocated using cpl_free() by the caller if it is no longer needed.
cpl_error_code cpl_plugin_init |
( |
cpl_plugin * |
self, |
|
|
unsigned int |
api, |
|
|
unsigned long |
version, |
|
|
unsigned long |
type, |
|
|
const char * |
name, |
|
|
const char * |
synopsis, |
|
|
const char * |
description, |
|
|
const char * |
author, |
|
|
const char * |
email, |
|
|
const char * |
copyright, |
|
|
cpl_plugin_func |
create, |
|
|
cpl_plugin_func |
execute, |
|
|
cpl_plugin_func |
destroy |
|
) |
| |
Initialise a plugin.
- Parameters
-
self | The plugin to initialise. |
api | The plugin interface version number. |
version | The plugin's version number. |
type | The plugin's type. |
name | The plugin's unique name. |
synopsis | The plugin's short description (purpose, synopsis ...). |
description | The plugin's detailed description. |
author | The plugin's author name. |
email | The plugin author's e-mail address. |
copyright | The plugin's copyright and licensing information. |
create | The function used to create the plugin. |
execute | The function used to execute the plugin. |
destroy | The function used to destroy the plugin. |
- Returns
- The function returns
CPL_ERROR_NONE
on success or a CPL error code otherwise.
- Errors
CPL_ERROR_NULL_INPUT | The parameter self is a NULL pointer. |
The function fills the cpl_plugin
part of a plugin structure. For information on which information is required and which is optional please refer to the documentation of the plugin structure cpl_plugin.
If self is not a valid pointer, the function returns immediately.
Create a new, empty plugin interface.
- Returns
- The pointer to a newly allocated plugin or
NULL
if it could not be created.
The function allocates memory for a cpl_plugin
and initialises it. The function returns a handle for the newly created plugin interface object. The created plugin interface must be destroyed using the plugin interface destructor cpl_plugin_delete().
Set the plugin interface version number.
- Parameters
-
self | A plugin |
api | The plugin interface version to set. |
- Returns
- The function returns
CPL_ERROR_NONE
on success or a CPL error code otherwise.
- Errors
CPL_ERROR_NULL_INPUT | The parameter self is a NULL pointer. |
This function sets the version number of the plugin interface of the plugin self to the version api.
- Attention
- The plugin interface version describes the internal layout of the plugin interface. It should be used by an application to decide whether a particular plugin can be used or not, i.e. if the plugin interface supported by the application is compatible with the interface presented by the plugin itself.
Set the name of the plugin author.
- Parameters
-
self | A plugin |
author | The name of the plugin author. |
- Returns
- The function returns
CPL_ERROR_NONE
on success or a CPL error code otherwise.
- Errors
CPL_ERROR_NULL_INPUT | The parameter self or author is a NULL pointer. |
This function copies the plugin author's name from the string author to the plugin self.
Set the license and copyright information of a plugin.
- Parameters
-
self | A plugin. |
copyright | The plugin's license information. |
- Note
- The license information must be compatible with that of CPL.
- Returns
- The function returns
CPL_ERROR_NONE
on success or a CPL error code otherwise.
- Errors
CPL_ERROR_NULL_INPUT | The parameter self or copyright is a NULL pointer. |
This function copies the plugin's license information from the string copyright to the plugin self.
Set the cleanup handler of a plugin.
- Parameters
-
self | A plugin |
func | The plugin's cleanup handler. |
- Returns
- The function returns
CPL_ERROR_NONE
on success or a CPL error code otherwise.
- Errors
CPL_ERROR_NULL_INPUT | The parameter self is a NULL pointer. |
This function installs the function func as the cleanup handler of the plugin self. The registered function is called after the plugin has been executed to release any acquired resources.
Set the detailed description of a plugin.
- Parameters
-
self | A plugin. |
description | The plugin's detailed description, or NULL . |
- Returns
- The function returns
CPL_ERROR_NONE
on success or a CPL error code otherwise.
- Errors
CPL_ERROR_NULL_INPUT | The parameter self is a NULL pointer. |
This function copies the detailed description text from the string description to the plugin self. The C formatting characters '\n'
and '\t'
may be embedded in the string description.
Set the contact information of a plugin.
- Parameters
-
self | A plugin. |
email | The plugin author's contact information. |
- Returns
- The function returns
CPL_ERROR_NONE
on success or a CPL error code otherwise.
- Errors
CPL_ERROR_NULL_INPUT | The parameter self is a NULL pointer. |
- Returns
- The function returns 0 on success, or a non-zero value otherwise. If self is not a valid pointer the function returns 1.
This function copies the plugin author contact information from the string email to the plugin self.
Set the execution handler of a plugin.
- Parameters
-
self | A plugin. |
func | The plugin's execution function. |
- Returns
- The function returns
CPL_ERROR_NONE
on success or a CPL error code otherwise.
- Errors
CPL_ERROR_NULL_INPUT | The parameter self is a NULL pointer. |
This function installs the function func as the execution function of the plugin self. The registered function must be called by an application after the plugin's initialisation function was called. Calling the registered function executes the plugin.
Set the initialisation handler of a plugin.
- Parameters
-
self | A plugin |
func | The plugin's initialisation function |
- Returns
- The function returns
CPL_ERROR_NONE
on success or a CPL error code otherwise.
- Errors
CPL_ERROR_NULL_INPUT | The parameter self is a NULL pointer. |
This function installs the function func as the initialisation function of the plugin self. The registered function must be called by an application before the plugin is executed.
Set the name of a plugin.
- Parameters
-
self | A plugin. |
name | The plugin's unique name. |
- Returns
- The function returns
CPL_ERROR_NONE
on success or a CPL error code otherwise.
- Errors
CPL_ERROR_NULL_INPUT | The parameter self or name is a NULL pointer. |
This function assigns the name name to the plugin self.
- Attention
- Since plugins are selected through their name this name should be choosen carefully in order to avoid name clashes with other plugins.
Set the short description of a plugin.
- Parameters
-
self | A plugin. |
synopsis | The plugin's synopsis, or NULL. |
- Returns
- The function returns
CPL_ERROR_NONE
on success or a CPL error code otherwise.
- Errors
CPL_ERROR_NULL_INPUT | The parameter self is a NULL pointer. |
This function copies the short description text from the string synopsis to the plugin self.
Set the type of a plugin.
- Parameters
-
self | A plugin. |
type | The plugin type to set. |
- Returns
- The function returns
CPL_ERROR_NONE
on success or a CPL error code otherwise.
- Errors
CPL_ERROR_NULL_INPUT | The parameter self is a NULL pointer. |
This function sets the type (cf. cpl_plugin_type) of the plugin self to type.
int cpl_plugin_set_version |
( |
cpl_plugin * |
self, |
|
|
unsigned long |
version |
|
) |
| |
Set the version number of a plugin.
- Parameters
-
self | A plugin |
version | The plugin's version number to set. |
- Returns
- The function returns
CPL_ERROR_NONE
on success or a CPL error code otherwise.
- Errors
CPL_ERROR_NULL_INPUT | The parameter self is a NULL pointer. |
This function sets the version number of the plugin interface of the plugin self to the version api.
This function sets the version number of the plugin self to version.