Corrade::PluginManager::AbstractManager class

Base for plugin managers.

See Manager and Plugin management for more information.

Derived classes

template<class T>
class Manager
Plugin manager.

Public static variables

static const int Version
Plugin version.

Constructors, destructors, conversion operators

AbstractManager(const AbstractManager&) deleted
Copying is not allowed.
AbstractManager(AbstractManager&&) deleted
Moving is not allowed.
~AbstractManager() protected
Destructor.

Public functions

auto operator=(const AbstractManager&) -> AbstractManager& deleted
Copying is not allowed.
auto operator=(AbstractManager&&) -> AbstractManager& deleted
Moving is not allowed.
auto pluginInterface() const -> Containers::StringView
Plugin interface.
auto pluginDirectory() const -> Containers::StringView
Plugin directory.
void setPluginDirectory(Containers::StringView directory)
Set another plugin directory.
void reloadPluginDirectory()
Reload plugin directory.
void setPreferredPlugins(Containers::StringView alias, std::initializer_list<Containers::StringView> plugins)
Set preferred plugins for given alias.
auto pluginList() const -> Containers::Array<Containers::StringView>
List of all available plugin names.
auto aliasList() const -> Containers::Array<Containers::StringView>
List of all available alias names.
auto metadata(Containers::StringView plugin) -> PluginMetadata*
Plugin metadata.
auto metadata(Containers::StringView plugin) const -> const PluginMetadata*
auto loadState(Containers::StringView plugin) const -> LoadState
Load state of a plugin.
auto load(Containers::StringView plugin) -> LoadState
Load a plugin.
auto unload(Containers::StringView plugin) -> LoadState
Unload a plugin.
void registerExternalManager(AbstractManager& manager) new in 2020.06
Register an external manager for resolving inter-manager dependencies.

Function documentation

Corrade::PluginManager::AbstractManager::~AbstractManager() protected

Destructor.

Destroys all plugin instances and unloads all plugins.

Containers::StringView Corrade::PluginManager::AbstractManager::pluginInterface() const

Plugin interface.

Only plugins with the same plugin interface string can be used in this plugin manager. The returned view is always both Containers::StringViewFlag::NullTerminated and Containers::StringViewFlag::Global.

Containers::StringView Corrade::PluginManager::AbstractManager::pluginDirectory() const

Plugin directory.

The returned view points to memory owned by the plugin manager and is only guaranteed to stay valid until the next call to setPluginDirectory() or until the manager gets destroyed. The view is always Containers::StringViewFlag::NullTerminated.

void Corrade::PluginManager::AbstractManager::setPluginDirectory(Containers::StringView directory)

Set another plugin directory.

Keeps loaded plugins untouched, removes unloaded plugins which are not existing anymore and adds newly found plugins. If the directory doesn't exist, no new plugins are added and only unloaded plugins get removed.

Expects that the directory is in UTF-8. If it's already Containers::StringViewFlag::NullTerminated, it's passed to system APIs directly, otherwise a null-terminated copy is allocated first. On Windows the path is instead first converted to UTF-16 using Utility::Unicode::widen() and then passed to system APIs.

If directory is Containers::StringViewFlag::Global, no internal copy of the string is made.

void Corrade::PluginManager::AbstractManager::reloadPluginDirectory()

Reload plugin directory.

Convenience equivalent to setPluginDirectory(pluginDirectory()).

void Corrade::PluginManager::AbstractManager::setPreferredPlugins(Containers::StringView alias, std::initializer_list<Containers::StringView> plugins)

Set preferred plugins for given alias.

By default, if more than one plugin provides given alias, one of them is arbitrarily chosen. With this function it's possible to control the behavior. For given alias the function goes through the list in plugins and uses the first plugin that is available. The alias is expected to exist and be defined by plugins in plugins. If none of plugins is available, nothing is done.

Note that after calling setPluginDirectory() or reloadPluginDirectory() this preference gets reset and you may need to call this function again.

If alias is Containers::StringViewFlag::Global, no internal copy of the string is made.

Containers::Array<Containers::StringView> Corrade::PluginManager::AbstractManager::pluginList() const

List of all available plugin names.

Returns a list of names that correspond to concrete unique static or dynamic plugins.

The returned views point to memory owned by the plugin manager and are only guaranteed to stay valid until the next call to setPluginDirectory(), reloadPluginDirectory(), load() or Manager::loadAndInstantiate() or until the manager gets destroyed.

Containers::Array<Containers::StringView> Corrade::PluginManager::AbstractManager::aliasList() const

List of all available alias names.

In addition to everything returned by pluginList() contains also all plugin aliases. The returned views point to memory owned by the plugin manager and are only guaranteed to stay valid until the next call to setPluginDirectory(), reloadPluginDirectory(), load() or Manager::loadAndInstantiate() or until the manager gets destroyed.

PluginMetadata* Corrade::PluginManager::AbstractManager::metadata(Containers::StringView plugin)

Plugin metadata.

Returns pointer to plugin metadata or nullptr, if given plugin is not found.

const PluginMetadata* Corrade::PluginManager::AbstractManager::metadata(Containers::StringView plugin) const

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

LoadState Corrade::PluginManager::AbstractManager::loadState(Containers::StringView plugin) const

Load state of a plugin.

Returns LoadState::Loaded if the plugin is loaded or LoadState::NotLoaded if not. For static plugins returns always LoadState::Static. On failure returns LoadState::NotFound or LoadState::WrongMetadataFile.

LoadState Corrade::PluginManager::AbstractManager::load(Containers::StringView plugin)

Load a plugin.

Returns LoadState::Loaded if the plugin is already loaded or if loading succeeded. For static plugins returns always LoadState::Static. On failure returns LoadState::NotFound, LoadState::WrongPluginVersion, LoadState::WrongInterfaceVersion, LoadState::UnresolvedDependency or LoadState::LoadFailed.

If the plugin has any dependencies, they are recursively processed before loading given plugin.

If plugin is a plugin file path (i.e., ending with a platform-specific extension such as .so or .dll), it's loaded from given location and, if the loading succeeds, its basename (without extension) is exposed as an available plugin name. It's expected that a plugin with the same name is not already loaded. The plugin will reside in the plugin list as long as it's loaded or, after calling unload() on it, until next call to setPluginDirectory() or reloadPluginDirectory().

If passing a file path, it's expected to be in UTF-8 and have forward slashes as directory separators. Use Utility::Path::fromNativeSeparators() to convert from platform-specific format. On Windows the path is first converted to UTF-16 using Utility::Unicode::widen() and then passed to system APIs.

An internal copy of plugin is made if it's not Containers::StringViewFlag::Global.

LoadState Corrade::PluginManager::AbstractManager::unload(Containers::StringView plugin)

Unload a plugin.

Returns LoadState::NotLoaded if the plugin is not loaded or unloading succeeded. For static plugins always returns LoadState::Static. On failure returns LoadState::NotFound, LoadState::UnloadFailed, LoadState::Required or LoadState::Used.

void Corrade::PluginManager::AbstractManager::registerExternalManager(AbstractManager& manager) new in 2020.06

Register an external manager for resolving inter-manager dependencies.

To be used for loading dependencies from different plugin interfaces. Once registered, the manager is expected to stay in scope for the whole lifetime of this instance.