plPlugin Class Reference

plPlugin manages all dynamically loadable plugins. More...

#include <Plugin.h>

Classes
struct	Init
struct	PluginInfo
	Contains basic information about a loaded plugin. More...

Static Public Member Functions
static const plCopyOnBroadcastEvent< const plPluginEvent & > &	Events ()
	Code that needs to be execute whenever a plugin is loaded or unloaded can register itself here to be notified of such events.
static void	InitializeStaticallyLinkedPlugins ()
	Calls the PL_PLUGIN_ON_LOADED() functions for all code that is already linked into the executable at startup.
static void	BeginPluginChanges ()
	Call this before loading / unloading several plugins in a row, to prevent unnecessary re-initializations.
static void	EndPluginChanges ()
	Must be called to finish what BeginPluginChanges started.
static bool	ExistsPluginFile (plStringView sPluginFile)
	Checks whether a plugin with the given name exists. Does not guarantee that the plugin could be loaded successfully.
static plResult	LoadPlugin (plStringView sPluginFile, plBitflags< plPluginLoadFlags > flags=plPluginLoadFlags::Default)
	Tries to load a DLL dynamically into the program.
static void	UnloadAllPlugins ()
	Unloads all previously loaded plugins in the reverse order in which they were loaded.
static void	SetMaxParallelInstances (plUInt32 uiMaxParallelInstances)
	Sets how many tries the system will do to find a free plugin file name.
static void	GetAllPluginInfos (plDynamicArray< PluginInfo > &ref_infos)
	Returns information about all currently loaded plugins.
static void	GetPluginPaths (plStringView sPluginName, plStringBuilder &ref_sOriginalFile, plStringBuilder &ref_sCopiedFile, plUInt8 uiFileCopyNumber)
static bool	PlatformNeedsPluginCopy ()

Detailed Description

plPlugin manages all dynamically loadable plugins.

To load a plugin, call plPlugin::LoadPlugin() with the filename of the plugin (without a path). The plugin DLL has to be located next to the application binary.

It is not possible to unload individual plugins, but you can unload all plugins. Make sure to only do this when no code and data from any of the plugins is still referenced somewhere.

When a plugin has a dependency on another plugin, it should contain a call to PL_PLUGIN_DEPENDENCY() in one of its cpp files. This instructs the system to load that plugin as well, and makes sure to delay initialization until all (transitive) dependencies are loaded.

A plugin may contain one or multiple PL_PLUGIN_ON_LOADED() and PL_PLUGIN_ON_UNLOADED() functions. These are called automatically once a plugin and all its dependencies are loaded. This can be used to make sure basic things get set up. For anything more complicated, use plStartup instead. Once a plugin is loaded, the startup system will initialize new startup code properly.

Member Function Documentation

InitializeStaticallyLinkedPlugins()

void plPlugin::InitializeStaticallyLinkedPlugins ( )

static

Calls the PL_PLUGIN_ON_LOADED() functions for all code that is already linked into the executable at startup.

If code that was meant to be loaded dynamically ends up being statically linked (e.g. on platforms where only static linking is used), the PL_PLUGIN_ON_LOADED() functions should still be called. The application can decide when the best time is. Usually a good point in time is right before the app would load the first dynamic plugin. If this function is never called manually, but plPlugin::LoadPlugin() is called, this function will be called automatically before loading the first actual plugin.

LoadPlugin()

plResult plPlugin::LoadPlugin ( plStringView sPluginFile, plBitflags< plPluginLoadFlags > flags = plPluginLoadFlags::Default )

static

Tries to load a DLL dynamically into the program.

PL_SUCCESS is returned when the DLL is either successfully loaded or has already been loaded before. PL_FAILURE is returned if the DLL cannot be located or it could not be loaded properly.

See plPluginLoadFlags for additional options.

SetMaxParallelInstances()

void plPlugin::SetMaxParallelInstances ( plUInt32 uiMaxParallelInstances )

static

Sets how many tries the system will do to find a free plugin file name.

During plugin loading the system may create copies of the plugin DLLs. This only works if the system can find a file to write to. If too many instances of the engine are running, no such free file name might be found and plugin loading fails. This value specifies how often the system tries to find a free file. The default is 32.

UnloadAllPlugins()

void plPlugin::UnloadAllPlugins ( )

static

Unloads all previously loaded plugins in the reverse order in which they were loaded.

Also calls PL_PLUGIN_ON_UNLOADED() of all statically linked code.

---

The documentation for this class was generated from the following files:

• Code/Engine/Foundation/Configuration/Plugin.h
• Code/Engine/Foundation/Configuration/Implementation/Android/Plugin_Android.h
• Code/Engine/Foundation/Configuration/Implementation/Plugin.cpp
• Code/Engine/Foundation/Configuration/Implementation/Posix/Plugin_Posix.h