iPluginManager Struct Reference (Crystal Space 2.0 Public API Reference)

| ## Public API Reference

- Main Page
- Related Pages
- Modules
- Namespaces
- Classes
- Files

- Class List
- Class Index
- Class Hierarchy
- Class Members

Public Types | Public Member Functions
iPluginManager Struct Reference
Shared Class Facility (SCF)

This is the plugin manager. More...

`#include <iutil/plugin.h>`

Inheritance diagram for iPluginManager:

List of all members.

## Public Types
enum | { lpiInitialize = 1, lpiReportErrors = 2, lpiLoadDependencies = 4, lpiReturnLoadedInstance = 8 }
| LoadPluginInstance flags. More...
## Public Member Functions
virtual void | Clear ()=0
| Unload all plugins from this plugin manager.
virtual csPtr< iStringArray > | GetClassIDTags (const char *classID)=0
| Get all tags mapped to that class ID.
virtual csPtr< iPluginIterator > | GetPluginInstances ()=0
| Get an iterator to iterate over all loaded plugins in the plugin manager.
virtual const char * | GetTagClassIDMapping (const char *tag)=0
| Get the class ID mapped to a tag.
virtual csPtr< iComponent > | LoadPluginInstance (const char *classID, uint loadFlags)=0
| Load a plugin (optionally loading dependencies) and (optionally) initialize it.
virtual csPtr< iComponent > | LoadTagPluginInstance (const char *tag, uint loadFlags)=0
| Load a plugin for a tag.
virtual void | QueryOptions (iComponent *object)=0
| Query all options supported by given plugin instance and place into OptionList.
virtual csPtr< iComponent > | QueryPluginInstance (const char *iInterface, int iVersion)=0
| Get one of the loaded plugins that supports given interface ID.
virtual csPtr< iComponent > | QueryTagPluginInstance (const char *tag)=0
| Query a plugin for a tag.
virtual bool | RegisterPluginInstance (const char *classID, iComponent *obj)=0
| Register a object that implements the iComponent interface as a plugin.
virtual bool | SetTagClassIDMapping (const char *tag, const char *classID)=0
| Set the class ID mapped to an object registry tag.
virtual bool | UnloadPluginInstance (iComponent *obj)=0
| Remove a plugin from the plugin manager's plugin list.
virtual bool | UnsetTagClassIDMapping (const char *tag)=0
| Remove a class ID mapping for a tag.
virtual csPtr< iComponent > | QueryPluginInstance (const char *classID)=0
| Find a plugin given its class ID.
virtual csPtr< iComponent > | QueryPluginInstance (const char *classID, const char *iInterface, int iVersion)=0
| Find a plugin given its class ID.

## Detailed Description

This is the plugin manager.

The plugin manager is guaranteed thread-safe.

Main creators of instances implementing this interface:

- csInitializer::CreateEnvironment()
- csInitializer::CreatePluginManager()

Main ways to get pointers to this interface:

- csQueryRegistry()

Definition at line 62 of file plugin.h.

## Member Enumeration Documentation

anonymous enum

LoadPluginInstance flags.

LoadPluginInstance

Enumerator:

  lpiInitialize | Initialize plugin.
  lpiReportErrors | Report loading errors.
  lpiLoadDependencies | Load dependent plugins.
  lpiReturnLoadedInstance | Return an existing instance of the plugin if it exists, else create a new one.

Definition at line 70 of file plugin.h.

## Member Function Documentation

virtual void iPluginManager::Clear | ( |  | ) | `[pure virtual]`

Unload all plugins from this plugin manager.

Implemented in csPluginManager.

virtual csPtr<iStringArray> iPluginManager::GetClassIDTags | ( | const char * | classID | ) | `[pure virtual]`

Get all tags mapped to that class ID.

classID can be wildcard (ending in '.') which means all class IDs starting with classID are considered,

Implemented in csPluginManager.

virtual csPtr<iPluginIterator> iPluginManager::GetPluginInstances | ( |  | ) | `[pure virtual]`

Get an iterator to iterate over all loaded plugins in the plugin manager.

This iterator will contain a copy of the plugins so it will not lock the plugin manager while looping over the plugins.

Implemented in csPluginManager.

virtual const char* iPluginManager::GetTagClassIDMapping | ( | const char * | tag | ) | `[pure virtual]`

Get the class ID mapped to a tag.

Implemented in csPluginManager.

virtual csPtr<iComponent> iPluginManager::LoadPluginInstance | ( | const char * | classID,
|  | uint | loadFlags
| ) |  | `[pure virtual]`

Load a plugin (optionally loading dependencies) and (optionally) initialize it.

If the lpiInitialize flag is given then the plugin will be initialized (that is, the iComponent's Initialize() method is called) and QueryOptions() will be called. This is risky. In a multi-threaded situation two threads may request the same plugin (almost) simultaneously; if one thread does not request initialization, but another thread does (and assumes to get an initialized instance), the other thread may in fact receive an uninitialized instance (and likely break). Use this flag with caution! If the lpiReportErrors flag is given then loading failures are reported using the reporter. If the lpiLoadDependencies flag is given dependent plugins (as specified in the plugin's metadata) will be loaded as well. Note that dependencies are *always* loaded.

Parameters:

  classID | Class ID of the plugin to load.
  loadFlags | Load options.

Implemented in csPluginManager.

virtual csPtr<iComponent> iPluginManager::LoadTagPluginInstance | ( | const char * | tag,
|  | uint | loadFlags
| ) |  | `[pure virtual]`

Load a plugin for a tag.

Canonically equivalent to LoadTagPluginInstance ( GetTagClassIDMapping (tag), loadFlags).

Implemented in csPluginManager.

virtual void iPluginManager::QueryOptions | ( | iComponent * | object | ) | `[pure virtual]`

Query all options supported by given plugin instance and place into OptionList.

Normally this is done automatically by LoadPlugin() if 'init' is true. If 'init' is not true then you can call this function AFTER calling object->Initialize().

Implemented in csPluginManager.

virtual csPtr<iComponent> iPluginManager::QueryPluginInstance | ( | const char * | iInterface,
|  | int | iVersion
| ) |  | `[pure virtual]`

Get one of the loaded plugins that supports given interface ID.

Warning:
  Usage of this function is usually not safe since multiple plugins can implement the same interface and there is no way to know which one is the correct one. This method will return a random plugin providing the given interface. It is usually better to use the object registry to obtain components with a certain interface.

Implemented in csPluginManager.

virtual csPtr<iComponent> iPluginManager::QueryPluginInstance | ( | const char * | classID | ) | `[pure virtual]`

Find a plugin given its class ID.

Warning:
  It is valid to load multiple plugin instances for the same plugin class IDs. If this is the case, querying for an instance of a plugin class ID will return a random loaded plugin instance.

Implemented in csPluginManager.

virtual csPtr<iComponent> iPluginManager::QueryPluginInstance | ( | const char * | classID,
|  | const char * | iInterface,
|  | int | iVersion
| ) |  | `[pure virtual]`

Find a plugin given its class ID.

Warning:
  It is valid to load multiple plugin instances for the same plugin class IDs. If this is the case, querying for an instance of a plugin class ID will return a random loaded plugin instance.

Implemented in csPluginManager.

virtual csPtr<iComponent> iPluginManager::QueryTagPluginInstance | ( | const char * | tag | ) | `[pure virtual]`

Query a plugin for a tag.

Canonically equivalent to QueryPluginInstance (GetTagClassIDMapping (tag)).

Implemented in csPluginManager.

virtual bool iPluginManager::RegisterPluginInstance | ( | const char * | classID,
|  | iComponent * | obj
| ) |  | `[pure virtual]`

Register a object that implements the iComponent interface as a plugin.

Implemented in csPluginManager.

virtual bool iPluginManager::SetTagClassIDMapping | ( | const char * | tag,
|  | const char * | classID
| ) |  | `[pure virtual]`

Set the class ID mapped to an object registry tag.

Tag mappings are used in dependency resolution while plugin loading.

Implemented in csPluginManager.

virtual bool iPluginManager::UnloadPluginInstance | ( | iComponent * | obj | ) | `[pure virtual]`

Remove a plugin from the plugin manager's plugin list.

Implemented in csPluginManager.

virtual bool iPluginManager::UnsetTagClassIDMapping | ( | const char * | tag | ) | `[pure virtual]`

Remove a class ID mapping for a tag.

Implemented in csPluginManager.

The documentation for this struct was generated from the following file:

- iutil/plugin.h