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_plugin *	cpl_pluginlist_find (cpl_pluginlist *self, const char *name)
	Find a plugin with a given name in a plugin list.
cpl_plugin *	cpl_pluginlist_get_first (cpl_pluginlist *self)
	Get the first plugin of a plugin list.
cpl_plugin *	cpl_pluginlist_get_last (cpl_pluginlist *self)
	Get the last plugin of a plugin list.
cpl_plugin *	cpl_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_pluginlist *	cpl_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

cpl_pluginlist

typedef struct _cpl_pluginlist_ cpl_pluginlist

The opaque plugin list data type.

Function Documentation

cpl_pluginlist_append()

cpl_error_code cpl_pluginlist_append	(	cpl_pluginlist *	self,
		const cpl_plugin *	plugin
	)

Append a plugin to a plugin list.

Parameters

self	A plugin list.
plugin	The 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.

References CPL_ERROR_NONE, and CPL_ERROR_NULL_INPUT.

cpl_pluginlist_delete()

void cpl_pluginlist_delete

(

cpl_pluginlist *

self

)

Delete a plugin list.

Parameters

self	The 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.

References cpl_plugin_delete().

cpl_pluginlist_dump()

void cpl_pluginlist_dump	(	const cpl_pluginlist *	self,
		FILE *	stream
	)

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

Parameters

self	The plugin list.
stream	The 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()

References cpl_plugin_dump().

cpl_pluginlist_find()

cpl_plugin * cpl_pluginlist_find	(	cpl_pluginlist *	self,
		const char *	name
	)

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

Parameters

self	The plugin list to query.
name	The 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.

References CPL_ERROR_NULL_INPUT, and cpl_plugin_get_name().

cpl_pluginlist_get_first()

cpl_plugin * cpl_pluginlist_get_first

(

cpl_pluginlist *

self

)

Get the first plugin of a plugin list.

Parameters

self	A 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.

References CPL_ERROR_NULL_INPUT.

cpl_pluginlist_get_last()

cpl_plugin * cpl_pluginlist_get_last

(

cpl_pluginlist *

self

)

Get the last plugin of a plugin list.

Parameters

self	A 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.

References CPL_ERROR_NULL_INPUT.

cpl_pluginlist_get_next()

cpl_plugin * cpl_pluginlist_get_next

(

cpl_pluginlist *

self

)

Get the next plugin from a plugin list.

Parameters

self	A 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.

References CPL_ERROR_ILLEGAL_INPUT, and CPL_ERROR_NULL_INPUT.

cpl_pluginlist_get_size()

int cpl_pluginlist_get_size

(

cpl_pluginlist *

self

)

Get the current size of a plugin list.

Parameters

self	A 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.

References CPL_ERROR_NULL_INPUT.

cpl_pluginlist_new()

cpl_pluginlist * cpl_pluginlist_new

(

void

)

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.

cpl_pluginlist_prepend()

cpl_error_code cpl_pluginlist_prepend	(	cpl_pluginlist *	self,
		const cpl_plugin *	plugin
	)

Prepend a plugin to a plugin list.

Parameters

self	A plugin list.
plugin	The 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.

References CPL_ERROR_NONE, and CPL_ERROR_NULL_INPUT.