Loading...
Searching...
No Matches
Plugin Interface

The basic plugin interface definition. More...

## Classes

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

## Macros

#define | CPL_PLUGIN_API
| Plugin API version.

## Typedefs

typedef struct _cpl_plugin_ | cpl_plugin
| The plugin data type.
typedef enum _cpl_plugin_type_ | cpl_plugin_type
| Data type used to store the plugin type code.

## Enumerations

enum | _cpl_plugin_type_ { CPL_PLUGIN_TYPE_NONE = 0 , CPL_PLUGIN_TYPE_RECIPE_V2 = (1 << 1) | CPL_PLUGIN_TYPE_RECIPE }
| Definition of plugin types. More...

## Functions

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.

## 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);
cpl_plugin_get_info
int cpl_plugin_get_info(cpl_pluginlist *cpl_plugin_list)
Append the plugin information to the given list.
cpl_pluginlist
struct _cpl_pluginlist_ cpl_pluginlist
The opaque plugin list data type.
Definition cpl_pluginlist.h:39

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>
  */

/**

## Macro Definition Documentation

## CPL_PLUGIN_API

#define CPL_PLUGIN_API

Plugin API version.

## Typedef Documentation

## cpl_plugin

typedef struct _cpl_plugin_ cpl_plugin

The plugin data type.

This defines the (public) plugin data type.

## cpl_plugin_type

typedef enum _cpl_plugin_type_ cpl_plugin_type

Data type used to store the plugin type code.

## Enumeration Type Documentation

## _cpl_plugin_type_

enum _cpl_plugin_type_

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_V2

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 = 1 << 0,

/** 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`.

## Function Documentation

## cpl_plugin_copy()

cpl_error_code cpl_plugin_copy | ( | cpl_plugin * | self,
|  | const cpl_plugin * | other )

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.

@error

CPL_ERROR_NULL_INPUT | The parameter self or other is a NULL pointer.

@enderror

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

References CPL_ERROR_NONE, and CPL_ERROR_NULL_INPUT.

## cpl_plugin_delete()

void cpl_plugin_delete | ( | cpl_plugin * | self | ) |

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.

Referenced by cpl_pluginlist_delete().

## cpl_plugin_dump()

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.

References cpl_plugin_get_api(), cpl_plugin_get_author(), cpl_plugin_get_copyright(), cpl_plugin_get_deinit(), cpl_plugin_get_description(), cpl_plugin_get_email(), cpl_plugin_get_exec(), cpl_plugin_get_init(), cpl_plugin_get_name(), cpl_plugin_get_synopsis(), cpl_plugin_get_type(), cpl_plugin_get_type_string(), cpl_plugin_get_version(), and cpl_plugin_get_version_string().

Referenced by cpl_pluginlist_dump().

## cpl_plugin_get_api()

unsigned int cpl_plugin_get_api | ( | const 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. If an error occurs the function returns 0 and sets an appropriate error code.

@error

CPL_ERROR_NULL_INPUT | The parameter self is a NULL pointer.

@enderror

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.

References CPL_ERROR_NULL_INPUT.

Referenced by cpl_plugin_dump().

## cpl_plugin_get_author()

const char * cpl_plugin_get_author | ( | const 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. If an error occurs the function returns `NULL` and sets an appropriate error code.

@error

CPL_ERROR_NULL_INPUT | The parameter self is a NULL pointer.

@enderror

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!

References CPL_ERROR_NULL_INPUT.

Referenced by cpl_plugin_dump().

## cpl_plugin_get_copyright()

const char * cpl_plugin_get_copyright | ( | const 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. If an error occurs the function returns `NULL` and sets an appropriate error code.

@error

CPL_ERROR_NULL_INPUT | The parameter self is a NULL pointer.

@enderror

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!

References CPL_ERROR_NULL_INPUT.

Referenced by cpl_plugin_dump().

## cpl_plugin_get_deinit()

cpl_plugin_func cpl_plugin_get_deinit | ( | const cpl_plugin * | self | ) |

Get the cleanup handler of a plugin.

Parameters

  self | A plugin.

Returns
  The plugin's cleanup handler. If an error occurs the function returns `NULL` and sets an appropriate error code.

@error

CPL_ERROR_NULL_INPUT | The parameter self is a NULL pointer.

@enderror

The function returns the cleanup handler of the plugin self.

References CPL_ERROR_NULL_INPUT.

Referenced by cpl_plugin_dump().

## cpl_plugin_get_description()

const char * cpl_plugin_get_description | ( | const 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. If an error occurs the function returns `NULL` and sets an appropriate error code.

@error

CPL_ERROR_NULL_INPUT | The parameter self is a NULL pointer.

@enderror

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!

References CPL_ERROR_NULL_INPUT.

Referenced by cpl_plugin_dump().

## cpl_plugin_get_email()

const char * cpl_plugin_get_email | ( | const 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. If an error occurs the function returns `NULL` and sets an appropriate error code.

@error

CPL_ERROR_NULL_INPUT | The parameter self is a NULL pointer.

@enderror

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!

References CPL_ERROR_NULL_INPUT.

Referenced by cpl_plugin_dump().

## cpl_plugin_get_exec()

cpl_plugin_func cpl_plugin_get_exec | ( | const cpl_plugin * | self | ) |

Get the execution handler of a plugin.

Parameters

  self | A plugin.

Returns
  The plugin's execution function. If an error occurs the function returns `NULL` and sets an appropriate error code.

@error

CPL_ERROR_NULL_INPUT | The parameter self is a NULL pointer.

@enderror

The function returns the execution function of the plugin self.

References CPL_ERROR_NULL_INPUT.

Referenced by cpl_plugin_dump().

## cpl_plugin_get_info()

int cpl_plugin_get_info | ( | cpl_pluginlist * | cpl_plugin_list | ) |

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

cpl_plugin_func cpl_plugin_get_init | ( | const cpl_plugin * | self | ) |

Get the initialisation handler of a plugin.

Parameters

  self | A plugin.

Returns
  The plugin's initalization function. If an error occurs the function returns `NULL` and sets an appropriate error code.

@error

CPL_ERROR_NULL_INPUT | The parameter self is a NULL pointer.

@enderror

The function returns the initalisation function of the plugin self.

References CPL_ERROR_NULL_INPUT.

Referenced by cpl_plugin_dump().

## cpl_plugin_get_name()

const char * cpl_plugin_get_name | ( | const 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. If an error occurs the function returns `NULL` and sets an appropriate error code.

@error

CPL_ERROR_NULL_INPUT | The parameter self is a NULL pointer.

@enderror

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.

References CPL_ERROR_NULL_INPUT.

Referenced by cpl_plugin_dump(), and cpl_pluginlist_find().

## cpl_plugin_get_synopsis()

const char * cpl_plugin_get_synopsis | ( | const 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. If an error occurs the function returns `NULL` and sets an appropriate error code.

@error

CPL_ERROR_NULL_INPUT | The parameter self is a NULL pointer.

@enderror

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!

References CPL_ERROR_NULL_INPUT.

Referenced by cpl_plugin_dump().

## cpl_plugin_get_type()

unsigned long cpl_plugin_get_type | ( | const cpl_plugin * | self | ) |

Get the type of a plugin.

Parameters

  self | A plugin.

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.

@error

CPL_ERROR_NULL_INPUT | The parameter self is a NULL pointer.

@enderror

This function returns the type (cf. cpl_plugin_type) of the plugin self.

References CPL_ERROR_NULL_INPUT, and CPL_PLUGIN_TYPE_NONE.

Referenced by cpl_plugin_dump().

## cpl_plugin_get_type_string()

char * cpl_plugin_get_type_string | ( | const cpl_plugin * | self | ) |

Get the type of a plugin as string.

Parameters

  self | A plugin.

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.

@error

CPL_ERROR_NULL_INPUT | The parameter self is a NULL pointer.

@enderror

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.

References CPL_ERROR_NULL_INPUT, and CPL_PLUGIN_TYPE_NONE.

Referenced by cpl_plugin_dump().

## cpl_plugin_get_version()

unsigned long cpl_plugin_get_version | ( | const cpl_plugin * | self | ) |

Get the version number of a plugin.

Parameters

  self | A plugin.

Returns
  The plugin's version number. If an error occurs the function returns 0 and sets an appropriate error code.

@error

CPL_ERROR_NULL_INPUT | The parameter self is a NULL pointer.

@enderror

This function returns the version number of the plugin self.

References CPL_ERROR_NULL_INPUT.

Referenced by cpl_plugin_dump().

## cpl_plugin_get_version_string()

char * cpl_plugin_get_version_string | ( | const 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. If an error occurs the function returns `NULL` and sets an appropriate error code.

@error

CPL_ERROR_NULL_INPUT | The parameter self is a NULL pointer.

@enderror

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.

References CPL_ERROR_NULL_INPUT, and cpl_sprintf().

Referenced by cpl_plugin_dump().

## cpl_plugin_init()

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.

@error

CPL_ERROR_NULL_INPUT | The parameter self is a NULL pointer.

@enderror

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.

References CPL_ERROR_NONE, CPL_ERROR_NULL_INPUT, cpl_plugin_set_api(), cpl_plugin_set_author(), cpl_plugin_set_copyright(), cpl_plugin_set_deinit(), cpl_plugin_set_description(), cpl_plugin_set_email(), cpl_plugin_set_exec(), cpl_plugin_set_init(), cpl_plugin_set_name(), cpl_plugin_set_synopsis(), cpl_plugin_set_type(), and cpl_plugin_set_version().

## cpl_plugin_new()

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

## cpl_plugin_set_api()

cpl_error_code 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 returns `CPL_ERROR_NONE` on success or a CPL error code otherwise.

@error

CPL_ERROR_NULL_INPUT | The parameter self is a NULL pointer.

@enderror

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.

References CPL_ERROR_NONE, and CPL_ERROR_NULL_INPUT.

Referenced by cpl_plugin_init().

## cpl_plugin_set_author()

cpl_error_code 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 `CPL_ERROR_NONE` on success or a CPL error code otherwise.

@error

CPL_ERROR_NULL_INPUT | The parameter self or author is a NULL pointer.

@enderror

This function copies the plugin author's name from the string author to the plugin self.

References CPL_ERROR_NONE, and CPL_ERROR_NULL_INPUT.

Referenced by cpl_plugin_init().

## cpl_plugin_set_copyright()

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

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.

@error

CPL_ERROR_NULL_INPUT | The parameter self or copyright is a NULL pointer.

@enderror

This function copies the plugin's license information from the string copyright to the plugin self.

References CPL_ERROR_NONE, and CPL_ERROR_NULL_INPUT.

Referenced by cpl_plugin_init().

## cpl_plugin_set_deinit()

cpl_error_code cpl_plugin_set_deinit | ( | 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 `CPL_ERROR_NONE` on success or a CPL error code otherwise.

@error

CPL_ERROR_NULL_INPUT | The parameter self is a NULL pointer.

@enderror

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.

References CPL_ERROR_NONE, and CPL_ERROR_NULL_INPUT.

Referenced by cpl_plugin_init().

## cpl_plugin_set_description()

cpl_error_code 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, or `NULL`.

Returns
  The function returns `CPL_ERROR_NONE` on success or a CPL error code otherwise.

@error

CPL_ERROR_NULL_INPUT | The parameter self is a NULL pointer.

@enderror

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.

References CPL_ERROR_NONE, and CPL_ERROR_NULL_INPUT.

Referenced by cpl_plugin_init().

## cpl_plugin_set_email()

cpl_error_code 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 `CPL_ERROR_NONE` on success or a CPL error code otherwise.

@error

CPL_ERROR_NULL_INPUT | The parameter self is a NULL pointer.

@enderror

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.

References CPL_ERROR_NONE, and CPL_ERROR_NULL_INPUT.

Referenced by cpl_plugin_init().

## cpl_plugin_set_exec()

cpl_error_code cpl_plugin_set_exec | ( | 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 `CPL_ERROR_NONE` on success or a CPL error code otherwise.

@error

CPL_ERROR_NULL_INPUT | The parameter self is a NULL pointer.

@enderror

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.

References CPL_ERROR_NONE, and CPL_ERROR_NULL_INPUT.

Referenced by cpl_plugin_init().

## cpl_plugin_set_init()

cpl_error_code cpl_plugin_set_init | ( | 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 `CPL_ERROR_NONE` on success or a CPL error code otherwise.

@error

CPL_ERROR_NULL_INPUT | The parameter self is a NULL pointer.

@enderror

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.

References CPL_ERROR_NONE, and CPL_ERROR_NULL_INPUT.

Referenced by cpl_plugin_init().

## cpl_plugin_set_name()

cpl_error_code 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 `CPL_ERROR_NONE` on success or a CPL error code otherwise.

@error

CPL_ERROR_NULL_INPUT | The parameter self or name is a NULL pointer.

@enderror

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.

References CPL_ERROR_NONE, and CPL_ERROR_NULL_INPUT.

Referenced by cpl_plugin_init().

## cpl_plugin_set_synopsis()

cpl_error_code 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, or NULL.

Returns
  The function returns `CPL_ERROR_NONE` on success or a CPL error code otherwise.

@error

CPL_ERROR_NULL_INPUT | The parameter self is a NULL pointer.

@enderror

This function copies the short description text from the string synopsis to the plugin self.

References CPL_ERROR_NONE, and CPL_ERROR_NULL_INPUT.

Referenced by cpl_plugin_init().

## cpl_plugin_set_type()

cpl_error_code 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 `CPL_ERROR_NONE` on success or a CPL error code otherwise.

@error

CPL_ERROR_NULL_INPUT | The parameter self is a NULL pointer.

@enderror

This function sets the type (cf. cpl_plugin_type) of the plugin self to type.

References CPL_ERROR_NONE, and CPL_ERROR_NULL_INPUT.

Referenced by cpl_plugin_init().

## cpl_plugin_set_version()

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.

@error

CPL_ERROR_NULL_INPUT | The parameter self is a NULL pointer.

@enderror

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.

References CPL_ERROR_NONE, and CPL_ERROR_NULL_INPUT.

Referenced by cpl_plugin_init().