Classes | |
struct | _cpl_plugin_ |
The type representation of the generic plugin interface. More... | |
Defines | |
#define | CPL_PLUGIN_API |
Plugin API version. | |
Typedefs | |
typedef enum _cpl_plugin_type_ | cpl_plugin_type |
Data type used to store the plugin type code. | |
typedef _cpl_plugin_ | cpl_plugin |
The plugin data type. | |
Enumerations | |
enum | _cpl_plugin_type_ { CPL_PLUGIN_TYPE_NONE = 0, CPL_PLUGIN_TYPE_RECIPE = 1 } |
Definition of plugin types. More... | |
Functions | |
cpl_plugin * | cpl_plugin_new (void) |
Create a new, empty plugin interface. | |
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. | |
cpl_error_code | cpl_plugin_set_api (cpl_plugin *self, unsigned int api) |
Set the plugin interface version number. | |
unsigned int | cpl_plugin_get_api (const cpl_plugin *self) |
Get the version number of the plugin interface implementation. | |
int | cpl_plugin_set_version (cpl_plugin *self, unsigned long version) |
Set the version number of a plugin. | |
unsigned long | cpl_plugin_get_version (const cpl_plugin *self) |
Get the version number of a plugin. | |
const 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_set_type (cpl_plugin *self, unsigned long type) |
Set the type of a plugin. | |
unsigned long | cpl_plugin_get_type (const cpl_plugin *self) |
Get the type of a plugin. | |
const char * | cpl_plugin_get_type_string (const cpl_plugin *self) |
Get the type of a plugin as string. | |
cpl_error_code | cpl_plugin_set_name (cpl_plugin *self, const char *name) |
Set the name of a plugin. | |
const char * | cpl_plugin_get_name (const cpl_plugin *self) |
Get 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. | |
const char * | cpl_plugin_get_synopsis (const cpl_plugin *self) |
Get the short description of a plugin. | |
cpl_error_code | cpl_plugin_set_description (cpl_plugin *self, const char *description) |
Set the detailed description of a plugin. | |
const char * | cpl_plugin_get_description (const cpl_plugin *self) |
Get the detailed description of a plugin. | |
cpl_error_code | cpl_plugin_set_author (cpl_plugin *self, const char *author) |
Set the name of the plugin author. | |
const char * | cpl_plugin_get_author (const cpl_plugin *self) |
Get the name of the plugin author. | |
cpl_error_code | cpl_plugin_set_email (cpl_plugin *self, const char *email) |
Set the contact information of a plugin. | |
const char * | cpl_plugin_get_email (const cpl_plugin *self) |
Get the contact information of a plugin. | |
cpl_error_code | cpl_plugin_set_copyright (cpl_plugin *self, const char *copyright) |
Set the license and copyright information of a plugin. | |
const char * | cpl_plugin_get_copyright (const cpl_plugin *self) |
Get the license and copyright information 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_plugin_func | cpl_plugin_get_init (const cpl_plugin *self) |
Get the initialisation handler 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_plugin_func | cpl_plugin_get_exec (const cpl_plugin *self) |
Get the execution handler 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_plugin_func | cpl_plugin_get_deinit (const cpl_plugin *self) |
Get the cleanup handler of a plugin. | |
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. | |
void | cpl_plugin_dump (const cpl_plugin *self, FILE *stream) |
Dump the plugin debugging information to the given stream. | |
int | cpl_plugin_get_info (cpl_pluginlist *list) |
Append the plugin information to the given list. |
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> cpl_plugin_get_info(cpl_pluginlist *list);
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.
#include <cpl_plugin.h>
|
Plugin API version.
|
|
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. |
|
Copy a plugin.
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).
cpl_plugin part of your derived plugin. Copy additional data members of the target plugin explicitely. |
|
Destroy a plugin.
cpl_plugin type is released and then the plugin itself is destroyed.
|
|
Dump the plugin debugging information to the given stream.
NULL the function writes to the standard output. If self is NULL the function does nothing. |
|
Get the version number of the plugin interface implementation.
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. |
|
Get the name of the plugin author.
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! |
|
Get the license and copyright information of a plugin.
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! |
|
Get the cleanup handler of a plugin.
The function returns the cleanup handler of the plugin self. |
|
Get the detailed description of a plugin.
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! |
|
Get the contact information of a plugin.
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! |
|
Get the execution handler of a plugin.
The function returns the execution function of the plugin self. |
|
Append the plugin information to the given list.
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 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. |
|
Get the initialisation handler of a plugin.
The function returns the initalisation function of the plugin self. |
|
Get the name of a plugin.
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. |
|
Get the short description of a plugin.
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! |
|
Get the type of a plugin.
This function returns the type (cf. cpl_plugin_type) of the plugin self. |
|
Get the type of a plugin as string.
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. |
|
Get the version number of a plugin.
This function returns the version number of the plugin self. |
|
Get the version number of a plugin as a string.
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. |
|
Initialise a plugin.
The function fills the If self is not a valid pointer, the function returns immediately. |
|
Create a new, empty plugin interface.
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.
This function sets the version number of the plugin interface of the plugin self to the version api.
|
|
Set the name of the plugin author.
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.
This function copies the plugin's license information from the string copyright to the plugin self. |
|
Set the cleanup handler of a plugin.
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.
This function copies the detailed description text from the string description to the plugin self. The C formatting characters |
|
Set the contact information of a plugin.
|
|
Set the execution handler of a plugin.
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.
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.
This function assigns the name name to the plugin self.
|
|
Set the short description of a plugin.
This function copies the short description text from the string synopsis to the plugin self. |
|
Set the type of a plugin.
This function sets the type (cf. cpl_plugin_type) of the plugin self to type. |
|
Set the version number of a plugin.
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. |