fdk::PluginRegistry Class Reference

Classes
struct	Directory

Public Types
using	DirectoryList = std::vector< Directory >

Public Member Functions
void	prependSearchPath (const char *)
	Adds a search path to the beginning of the path list.
void	appendSearchPath (const char *)
	Adds a search path to the end of the path list.
size_t	numSearchPaths () const
	Returns the number of total search path strings, which is also the total number of Directories.
const StringList &	searchPaths () const
	Returns the list of search paths.
const DirectoryList &	directories () const
const Directory &	directory (size_t i) const
	Retrieve the Directory entry.
const Directory &	findDirectoryForPath (const char *filepath) const
const Directory &	findOrAddDirectory (const char *directory_name, size_t name_length=0)
const StringList &	pluginExtensions () const
std::filesystem::path	findPlugin (const char *plugin_name, const StringList *extensions=nullptr)
PluginHandle	loadPlugin (const char *plugin_name, const StringList *extensions=nullptr)
const std::string &	lastLoadedPlugin () const
bool	haveLoadError () const
const std::string &	lastLoadedError () const
void	setLastLoadedError (const char *error_message)
const StringList &	loadedPlugins () const
	Returns the list of paths to all successfully loaded plugins, last loaded at end.

Protected Member Functions
	PluginRegistry (const PluginRegistry &)=delete
PluginRegistry &	operator= (const PluginRegistry &)=delete
virtual void	_initializeSearchPaths ()=0
virtual bool	_isValidPlugin (const char *, const std::filesystem::path &, PluginHandle) const

Protected Attributes
StringList	_searchPaths
	List of directory paths in search order, starting with 0.
DirectoryList	_directories
	List of directory contents in search order (matching _searchPaths)
StringList	_loadedPlugins
	Names of plugins already loaded, last loaded at end.
std::string	_lastLoadedError
	Contains the error message from the last loaded plugin, or empty if no error.
StringList	_extensions
	List of possible extensions to check, in priority order (with 0 = highest)

Member Function Documentation

directories()

const DirectoryList & fdk::PluginRegistry::directories

(

)

const

Returns the list of directories the registry will search to find a plugin. The indexing of this list will match searchPaths().

findDirectoryForPath()

const Directory & fdk::PluginRegistry::findDirectoryForPath

(

const char *

filepath

)

const

Returns the Directory containing the file in filepath if it exists in the registry, otherwise an empty(invalid) Directory is returned.

findOrAddDirectory()

const Directory & fdk::PluginRegistry::findOrAddDirectory	(	const char *	directory_name,
		size_t	name_length = 0
	)

Returns the Directory matching directory_name if it exists in the registry, otherwise a new Directory is added with that name. If name_length is non-zero then only that portion of the directory_name string is used as for the name search.

pluginExtensions()

const StringList & fdk::PluginRegistry::pluginExtensions ( ) const

inline

List of default extensions that findPlugin() will append to the plugin name and search for, in priority order.

findPlugin()

std::filesystem::path fdk::PluginRegistry::findPlugin	(	const char *	plugin_name,
		const StringList *	extensions = nullptr
	)

Attempt to find a plugin matching plugin_name with each possible extension inside each of the search directories, returning the path to the plugin file. If the extensions list is explicitly provided they are used instead of the current list in the registry.

loadPlugin()

PluginHandle fdk::PluginRegistry::loadPlugin	(	const char *	plugin_name,
		const StringList *	extensions = nullptr
	)

Attempt to find and load a plugin matching plugin_name with each possible extension inside each of the search directories. If plugin_name starts with a '\' or '/' then it's assumed to be an absolute file path and the plugin file directly loaded, skipping the search and extension matching. If the extensions list is explicitly provided it's used instead of the current list in the registry. If the plugin file is loaded without error it is added to the end of the loadedPlugins() list and the pointer to it returned, otherwise the error message from the failed load is retrieved via lastLoadedError().

lastLoadedPlugin()

const std::string & fdk::PluginRegistry::lastLoadedPlugin

(

)

const

Returns the path of the most recently loaded plugin file, or empty if error has occurred, found in lastLoadedError().

_initializeSearchPaths()

virtual void fdk::PluginRegistry::_initializeSearchPaths ( )

protectedpure virtual

Called the first time the registry is asked for the list of paths. A subclass should add the plugin search paths needed for basic functionality such as directories relative to the application or library install location. Must implement.

_isValidPlugin()

virtual bool fdk::PluginRegistry::_isValidPlugin ( const char *  , const std::filesystem::path &  , PluginHandle    ) const

inlineprotectedvirtual

Check that a loaded plugin file object is ok for the client dcc. Can be used for binary validation, checking for symbols, or license checks. Called when a plugin file has successfully loaded inside loadPlugin(), but before it's been added to the _loadedPlugins list. If this method returns false the plugin is unloaded and loadPlugin() returns a null PluginHandle. A clent dcc can fille in setLastLoadedError() with whatever it needs to communicate the reason why the plugin was rejected. Default implementation returns true.