Common Pipeline Library Reference Manual  5.3.1
Typedefs | Functions
Plugin List

Typedefs

typedef struct _cpl_pluginlist_ cpl_pluginlist
 The opaque plugin list data type.

Functions

cpl_error_code cpl_pluginlist_append (cpl_pluginlist *self, const cpl_plugin *plugin)
 Append a plugin to a plugin list.
void cpl_pluginlist_delete (cpl_pluginlist *self)
 Delete a plugin list.
void cpl_pluginlist_dump (const cpl_pluginlist *self, FILE *stream)
 Dump the contents of a plugin list to the given stream.
cpl_plugincpl_pluginlist_find (cpl_pluginlist *self, const char *name)
 Find a plugin with a given name in a plugin list.
cpl_plugincpl_pluginlist_get_first (cpl_pluginlist *self)
 Get the first plugin of a plugin list.
cpl_plugincpl_pluginlist_get_last (cpl_pluginlist *self)
 Get the last plugin of a plugin list.
cpl_plugincpl_pluginlist_get_next (cpl_pluginlist *self)
 Get the next plugin from a plugin list.
int cpl_pluginlist_get_size (cpl_pluginlist *self)
 Get the current size of a plugin list.
cpl_pluginlistcpl_pluginlist_new (void)
 Creates an empty plugin list.
cpl_error_code cpl_pluginlist_prepend (cpl_pluginlist *self, const cpl_plugin *plugin)
 Prepend a plugin to a plugin list.

Detailed Description

This module implements a list container for plugin objects and provides the facilities to query, to traverse and to update the container. The purpose of this container is to be able to store references to available plugins and to handle sets of plugins as a whole.

Since the plugin list just stores pointers to cpl_plugin, a plugin list may contain plugins of different kind at the same time, because all context specific plugins inherit the cpl_plugin type (see Plugin Interface).

Synopsis:
   #include <cpl_pluginlist.h>

Typedef Documentation

typedef struct _cpl_pluginlist_ cpl_pluginlist

The opaque plugin list data type.


Function Documentation

Append a plugin to a plugin list.

Parameters:
selfA plugin list.
pluginThe plugin to append.
Returns:
The function returns CPL_ERROR_NONE on success or a CPL error code otherwise.
Errors:
CPL_ERROR_NULL_INPUT The parameter self or plugin is a NULL pointer.

The plugin plugin is inserted into the plugin list self after the last element.

If self does not point to a valid plugin list, or if plugin is not a valid pointer the function returns immediately.

Delete a plugin list.

Parameters:
selfThe plugin list to delete.
Returns:
Nothing.

The function deletes the plugin list self and destroys all plugins the list potentially contains. If self is NULL, nothing is done and no error is set.

void cpl_pluginlist_dump ( const cpl_pluginlist self,
FILE *  stream 
)

Dump the contents of a plugin list to the given stream.

Parameters:
selfThe plugin list.
streamThe output stream to use.
Returns:
Nothing.

The function dumps the debugging information for each plugin found in the plugin list self to the output stream stream. The debugging information for each individual plugin is dumped using cpl_plugin_dump(). If self is NULL the function does nothing.

See also:
cpl_plugin_dump()
cpl_plugin* cpl_pluginlist_find ( cpl_pluginlist self,
const char *  name 
)

Find a plugin with a given name in a plugin list.

Parameters:
selfThe plugin list to query.
nameThe plugin's unique name to look for.
Returns:
The first plugin with the given name name, or NULL if it no plugin with this name could be found. The function returns NULL if an error occurs and sets an appropriate error code.
Errors:
CPL_ERROR_NULL_INPUT The parameter self or name is a NULL pointer.

This function searches the plugin list self for a plugin with the unique name name and returns a pointer to the first one found. If no plugin with the given name is found the function returns NULL.

Get the first plugin of a plugin list.

Parameters:
selfA plugin list.
Returns:
The first plugin stored in the plugin list self, or NULL if the list is empty. The function returns NULL if an error occurs and sets an appropriate error code.
Errors:
CPL_ERROR_NULL_INPUT The parameter self is a NULL pointer.

The function returns a handle to the first plugin stored in the self.

Get the last plugin of a plugin list.

Parameters:
selfA plugin list.
Returns:
The last plugin stored in the plugin list self, or NULL if the list is empty. The function returns NULL if an error occurs and sets an appropriate error code.
Errors:
CPL_ERROR_NULL_INPUT The parameter self is a NULL pointer.

The function returns a pointer to the last plugin stored in the plugin list self.

Get the next plugin from a plugin list.

Parameters:
selfA plugin list.
Returns:
The function returns the next plugin in the list, or NULL if the end of the list has been reached. The function returns NULL if an error occurs and sets an appropriate error code.
Errors:
CPL_ERROR_NULL_INPUT The parameter self is a NULL pointer.
CPL_ERROR_ILLEGAL_INPUT The function was called without initialising the plugin list self by calling cpl_pluginlist_first().

The function returns the next plugin in self. To find the next plugin, the plugin list caches the position of the most recently obtained plugin. This requires a call to cpl_pluginlist_get_first() prior to calling this function in order to properly initialise the internal cache.

If the end of self has been reached the internal cache is reset to the first plugin in the list.

Get the current size of a plugin list.

Parameters:
selfA plugin list.
Returns:
The plugin list's current size, or 0 if the list is empty. The function returns 0 if an error occurs and sets an appropriate error code.
Errors:
CPL_ERROR_NULL_INPUT The parameter self is a NULL pointer.

The function reports the current number of plugins stored in the plugin list self. If self does not point to a valid plugin list the function returns 0.

Creates an empty plugin list.

Returns:
The newly created plugin list, or NULL if it could not be created.

The function allocates memory for a plugin list object and initialises it to be empty.

Prepend a plugin to a plugin list.

Parameters:
selfA plugin list.
pluginThe plugin to prepend.
Returns:
The function returns CPL_ERROR_NONE on success or a CPL error code otherwise.
Errors:
CPL_ERROR_NULL_INPUT The parameter self or plugin is a NULL pointer.

The plugin plugin is inserted into the plugin list self before the first element.

If self does not point to a valid plugin list, or if plugin is not a valid pointer the function returns immediately.