Main Page   Modules   Alphabetical List   Compound List   Compound Members  

Plugin Interface

The basic plugin interface definition. More...

Compounds

struct  _cpl_plugin_
 The type representation of the generic plugin interface. More...


Defines

#define CPL_PLUGIN_API
 Plugin API version. More...


Typedefs

typedef enum _cpl_plugin_type_ cpl_plugin_type
 Data type used to store the plugin type code. More...

typedef _cpl_plugin_ cpl_plugin
 The plugin data type. More...


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. More...

void cpl_plugin_copy (cpl_plugin *self, const cpl_plugin *plugin)
 Copy a plugin. More...

void cpl_plugin_delete (cpl_plugin *plugin)
 Destroy a plugin. More...

void cpl_plugin_initfill (cpl_plugin *self)
 Initialise a plugin to be empty. More...

cpl_plugin * cpl_plugin_duplicate (const cpl_plugin *plugin)
 Create a duplicate of a plugin. More...

int cpl_plugin_set_api (cpl_plugin *self, unsigned int api)
 Set the plugin interface version number. More...

unsigned int cpl_plugin_get_api (cpl_plugin *self)
 Get the version number of the plugin interface implementation. More...

int cpl_plugin_set_version (cpl_plugin *self, unsigned long version)
 Set the version number of a plugin. More...

unsigned long cpl_plugin_get_version (cpl_plugin *self)
 Get the version number of a plugin. More...

const char * cpl_plugin_get_version_as_string (cpl_plugin *self)
 Get the version number of a plugin as a string. More...

int cpl_plugin_set_type (cpl_plugin *self, unsigned long type)
 Set the type of a plugin. More...

unsigned long cpl_plugin_get_type (cpl_plugin *self)
 Get the type of a plugin. More...

const char * cpl_plugin_get_type_as_string (cpl_plugin *self)
 Get the type of a plugin as string. More...

int cpl_plugin_set_name (cpl_plugin *self, const char *name)
 Set the name of a plugin. More...

const char * cpl_plugin_get_name (cpl_plugin *self)
 Get the name of a plugin. More...

int cpl_plugin_set_synopsis (cpl_plugin *self, const char *synopsis)
 Set the short description of a plugin. More...

const char * cpl_plugin_get_synopsis (cpl_plugin *self)
 Get the short description of a plugin. More...

int cpl_plugin_set_description (cpl_plugin *self, const char *description)
 Set the detailed description of a plugin. More...

const char * cpl_plugin_get_description (cpl_plugin *self)
 Get the detailed description of a plugin. More...

int cpl_plugin_set_author (cpl_plugin *self, const char *author)
 Set the name of the plugin author. More...

const char * cpl_plugin_get_author (cpl_plugin *self)
 Get the name of the plugin author. More...

int cpl_plugin_set_email (cpl_plugin *self, const char *email)
 Set the contact information of a plugin. More...

const char * cpl_plugin_get_email (cpl_plugin *self)
 Get the contact information of a plugin. More...

int cpl_plugin_set_copyright (cpl_plugin *self, const char *copyright)
 Set the license and copyright information of a plugin. More...

const char * cpl_plugin_get_copyright (cpl_plugin *self)
 Get the license and copyright information of a plugin. More...

int cpl_plugin_set_initialize (cpl_plugin *self, cpl_plugin_func func)
 Set the initialisation handler of a plugin. More...

cpl_plugin_func cpl_plugin_get_initialize (cpl_plugin *self)
 Get the initialisation handler of a plugin. More...

int cpl_plugin_set_execute (cpl_plugin *self, cpl_plugin_func func)
 Set the execution handler of a plugin. More...

cpl_plugin_func cpl_plugin_get_execute (cpl_plugin *self)
 Get the execution handler of a plugin. More...

int cpl_plugin_set_deinitialize (cpl_plugin *self, cpl_plugin_func func)
 Set the cleanup handler of a plugin. More...

cpl_plugin_func cpl_plugin_get_deinitialize (cpl_plugin *self)
 Get the cleanup handler of a plugin. More...

void 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. More...

void cpl_plugin_print (cpl_plugin *self)
 Print the contents of a plugin. More...

int cpl_plugin_get_info (cpl_pluginlist *list)
 Append the plugin information to the given list. More...


Detailed Description

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>

   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.

Synopsis:
   #include <cpl_plugin.h>

Define Documentation

#define CPL_PLUGIN_API
 

Plugin API version.


Typedef Documentation

typedef struct _cpl_plugin_ cpl_plugin
 

The plugin data type.

This defines the (public) plugin data type.

typedef enum _cpl_plugin_type_ cpl_plugin_type
 

Data type used to store the plugin type code.


Enumeration Type Documentation

enum _cpl_plugin_type_
 

Definition of plugin types.

Predefined plugin types supported by the Common Pipeline Library itself.

Enumeration values:
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.


Function Documentation

void cpl_plugin_copy cpl_plugin   self,
const cpl_plugin   plugin
 

Copy a plugin.

Parameters:
self  A plugin.
plugin  The plugin structure to copy.
Returns:
Nothing.
The function copies all members of the plugin plugin to the plugin structure self. The plugin plugin and its copy self do not share any resources after the copy operation. If either self, or plugin are invalid pointers, the function returns immediately.

Note that the plugins self and plugin do not need to be of the same kind (see below).

The suggested usage of this function is: If you do not have already created your target plugin self, allocate a memory block with the appropriate size to hold your derived plugin. Pass both, the target plugin (as self) and the source plugin (as plugin) to this function. The function will fill the cpl_plugin part of self. Additional, plugin type specific, structure members of self or plugin may be handled at this point.

Attention:
Be aware that the function copies only the cpl_plugin part of a derived plugin. All members defined in addition by the derived plugin are left untouched and must be copied explicitly.

void cpl_plugin_delete cpl_plugin   plugin
 

Destroy a plugin.

Parameters:
plugin  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 be 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.

cpl_plugin* cpl_plugin_duplicate const cpl_plugin   plugin
 

Create a duplicate of a plugin.

Parameters:
plugin  The plugin to duplicate.
Returns:
The pointer to the newly created duplicate, or NULL if it could not be created.
The function allocates memory for a duplicate of the plugin plugin and initialises the newly created plugin with the contens of the given plugin. The duplicate and the plugin plugin do not share any resources.

Attention:
In most cases this function will not work as expected because of data slicing. It is useful only in very rare cases and its usage is strongly discouraged! Use cpl_plugin_copy() instead!
Warning:
If a context specific plugin is passed to this function which was derived from the cpl_plugin type, the function will only create a duplicate from the cpl_plugin base of the context specific plugin, i.e. any structure members the context specific plugin may have in addition are lost (data slicing). This means that casting the returned pointer to cpl_plugin into a pointer to the derived plugin type is invalid!
See also:
cpl_plugin_copy()

unsigned int cpl_plugin_get_api cpl_plugin   self
 

Get the version number of the plugin interface implementation.

Parameters:
self  A plugin.
Returns:
The version number of the plugin interface implementation the plugin self complies with, or 0 if self is not a valid 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 cpl_plugin   self
 

Get the name of the plugin author.

Parameters:
self  A plugin.
Returns:
The function returns a pointer to the plugin author's name string, or NULL in case of errors.
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 cpl_plugin   self
 

Get the license and copyright information of a plugin.

Parameters:
self  A plugin.
Returns:
The function returns a pointer to the plugin's copyright information string, or NULL in case of errors.
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_deinitialize cpl_plugin   self
 

Get the cleanup handler of a plugin.

Parameters:
self  A plugin.
Returns:
The plugin's cleanup handler, or NULL in case of errors.
The function returns the cleanup handler of the plugin self.

const char* cpl_plugin_get_description cpl_plugin   self
 

Get the detailed description of a plugin.

Parameters:
self  A plugin.
Returns:
The function returns a pointer to the plugin's detailed description string, or NULL in case of errors.
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 cpl_plugin   self
 

Get the contact information of a plugin.

Parameters:
self  A plugin.
Returns:
The function returns a pointer to the plugin author's contact information string, or NULL in case of errors.
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_execute cpl_plugin   self
 

Get the execution handler of a plugin.

Parameters:
self  A plugin.
Returns:
The plugin's execution function, or NULL in case of errors.
The function returns the execution function of the plugin self.

int cpl_plugin_get_info cpl_pluginlist   list
 

Append the plugin information to the given list.

Parameters:
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_initialize cpl_plugin   self
 

Get the initialisation handler of a plugin.

Parameters:
self  A plugin.
Returns:
The plugin's initalization function, or NULL in case of errors.
The function returns the initalisation function of the plugin self.

const char* cpl_plugin_get_name cpl_plugin   self
 

Get the name of a plugin.

Parameters:
self  A plugin.
Returns:
The function returns a pointer to the plugin's unique name string, or NULL in case of errors.
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 cpl_plugin   self
 

Get the short description of a plugin.

Parameters:
self  A plugin.
Returns:
The function returns a pointer to the plugin's short description string, or NULL in case of errors.
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 cpl_plugin   self
 

Get the type of a plugin.

Parameters:
self  A plugin.
Returns:
The function returns the plugin type code. If self is not a valid pointer, the returned type code is CPL_PLUGIN_TYPE_NONE.
This function returns the type (cf. cpl_plugin_type) of the plugin self.

const char* cpl_plugin_get_type_as_string cpl_plugin   self
 

Get the type of a plugin as string.

Parameters:
self  A plugin.
Returns:
The string representation of the plugin type, or NULL in case of errors.
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 cpl_plugin   self
 

Get the version number of a plugin.

Parameters:
self  A plugin.
Returns:
The plugin's version number, or 0 if self does not point to a valid plugin.
This function returns the version number of the plugin self.

const char* cpl_plugin_get_version_as_string cpl_plugin   self
 

Get the version number of a plugin as a string.

Parameters:
self  A plugin.
Returns:
The string representation of the plugin's version number, or NULL in case of errors.
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.

void 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 unqique 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:
Nothing.
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.

void cpl_plugin_initfill cpl_plugin   self
 

Initialise a plugin to be empty.

Parameters:
self  The plugin to initialise.
Returns:
Nothing.
The function initialises the given cpl_plugin structure self so that it is a valid empty plugin. If self does not point to a valid plugin the function returns immediately.

cpl_plugin* cpl_plugin_new void   
 

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().

void cpl_plugin_print cpl_plugin   self
 

Print the contents of a plugin.

Parameters:
self  A plugin.
Returns:
Nothing.
The function prints the current contents of the plugin structure self using the currently installed print handler. By default the output is written to the standard output.

Note:
The function is provided only for debugging purposes.

int cpl_plugin_set_api cpl_plugin   self,
unsigned int    api
 

Set the plugin interface version number.

Parameters:
self  A plugin
api  The plugin interface version to set.
Returns:
The function return 0 on success, or a non-zero value otherwise. If self does not point to a valid plugin, the function returns 1.
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.

int cpl_plugin_set_author cpl_plugin   self,
const char *    author
 

Set the name of the plugin author.

Parameters:
self  A plugin
author  The name of the plugin author.
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's name from the string author to the plugin self.

int cpl_plugin_set_copyright cpl_plugin   self,
const char *    copyright
 

Set the license and copyright information of a plugin.

Parameters:
self  A plugin.
copyright  The plugin's license information.
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's license information from the string copyright to the plugin self.

int cpl_plugin_set_deinitialize cpl_plugin   self,
cpl_plugin_func    func
 

Set the cleanup handler of a plugin.

Parameters:
self  A plugin
func  The plugin's cleanup handler.
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 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.

int cpl_plugin_set_description cpl_plugin   self,
const char *    description
 

Set the detailed description of a plugin.

Parameters:
self  A plugin.
description  The plugin's detailed description.
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 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.

int cpl_plugin_set_email cpl_plugin   self,
const char *    email
 

Set the contact information of a plugin.

Parameters:
self  A plugin.
email  The plugin author's contact information.
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.

int cpl_plugin_set_execute cpl_plugin   self,
cpl_plugin_func    func
 

Set the execution handler of a plugin.

Parameters:
self  A plugin.
func  The plugin's execution function.
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 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.

int cpl_plugin_set_initialize cpl_plugin   self,
cpl_plugin_func    func
 

Set the initialisation handler of a plugin.

Parameters:
self  A plugin
func  The plugin's initialisation function
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 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.

int cpl_plugin_set_name cpl_plugin   self,
const char *    name
 

Set the name of a plugin.

Parameters:
self  A plugin.
name  The plugin's unique name.
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 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.

int cpl_plugin_set_synopsis cpl_plugin   self,
const char *    synopsis
 

Set the short description of a plugin.

Parameters:
self  A plugin.
synopsis  The plugin's synopsis.
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 short description text from the string synopsis to the plugin self.

int cpl_plugin_set_type cpl_plugin   self,
unsigned long    type
 

Set the type of a plugin.

Parameters:
self  A plugin.
type  The plugin type to set.
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 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 return 0 on success, or a non-zero value otherwise. If self does not point to a valid plugin, the function returns 1.
This function sets the version number of the plugin self to version.


Generated on Mon May 24 14:58:06 2004 for Common Pipeline Library Reference Manual by doxygen1.2.14 written by Dimitri van Heesch, © 1997-2002