Loading a Plugin

Using the AudioWeaver Plugin API to load plugin libraries. More...

Data Structures
struct	_awe_PluginLoaderMethods
	Method table to provide overrides to awe_PluginLoader_initWithMethods. More...

Typedefs
typedef struct _awe_PluginLoaderMethods	awe_PluginLoaderMethods
	Method table to provide overrides to awe_PluginLoader_initWithMethods. More...

Enumerations
enum	awe_PluginLoader_Status {   AWE_PLUGIN_LOADER_SUCCESS = 0 , AWE_PLUGIN_LOADER_UNINITIALIZED = -1 , AWE_PLUGIN_LOADER_ALREADY_INITIALIZED = -2 , AWE_PLUGIN_LOADER_MISSING_METHOD = -3 ,   AWE_PLUGIN_LOADER_ALLOCATION_FAILED = -4 , AWE_PLUGIN_LOADER_INVALID_INDEX = -5 , AWE_PLUGIN_LOADER_DL_OPEN_FAILED = -6 , AWE_PLUGIN_LOADER_DL_SYMBOL_NOT_FOUND = -7 ,   AWE_PLUGIN_LOADER_DL_INTERNAL_FAILURE = -8 }
	Possible statuses which may be returned by plugin loader API functions. More...

Functions
enum awe_PluginLoader_Status	awe_PluginLoader_init (size_t reserved_count)
	Initialize the plugin loader. More...
enum awe_PluginLoader_Status	awe_PluginLoader_initWithMethods (size_t reserved_count, const awe_PluginLoaderMethods *const overrides)
	Initialize the plugin loader with a set of override callbacks. More...
enum awe_PluginLoader_Status	awe_PluginLoader_load (const AWEPlugin **plugin, const char *file)
	Load a plugin library. More...
enum awe_PluginLoader_Status	awe_PluginLoader_unload (const char *file)
	Unload a plugin library. More...
enum awe_PluginLoader_Status	awe_PluginLoader_loadWithNamespacePrefix (const AWEPlugin **plugin, const char *file, const char *prefix)
	Load a plugin library with a namespaced entrypoint name. More...
enum awe_PluginLoader_Status	awe_PluginLoader_loadWithEntrypoint (const AWEPlugin **plugin, const char *file, const char *entrypoint)
	Load a plugin library with a custom entrypoint name. More...
size_t	awe_PluginLoader_count ()
	Get the number of currently loaded plugins. More...
enum awe_PluginLoader_Status	awe_PluginLoader_get (const AWEPlugin **plugin, size_t index)
	Retrieve a loaded plugin by index. More...
enum awe_PluginLoader_Status	awe_PluginLoader_find (const AWEPlugin **plugin, const char *file)
	Retrieve a loaded plugin by file name. More...
void	awe_PluginLoader_free ()
	Clean up the plugin loader. More...
const char *	awe_PluginLoader_statusToString (const enum awe_PluginLoader_Status status)
	Get a description of the given status. More...

Detailed Description

Using the AudioWeaver Plugin API to load plugin libraries.

For information on how to create a plugin, see Creating a Plugin.

Typedef Documentation

awe_PluginLoaderMethods

typedef struct _awe_PluginLoaderMethods awe_PluginLoaderMethods

Method table to provide overrides to awe_PluginLoader_initWithMethods.

This struct defines a set of function pointers which are used by awe_PluginLoader to perform memory allocation, dynamic library loading, and symbol resolution. It should be passed to awe_PluginLoader_initWithMethods. To avoid overriding a default value, leave it null.

Enumeration Type Documentation

awe_PluginLoader_Status

enum awe_PluginLoader_Status

Possible statuses which may be returned by plugin loader API functions.

Enumerator
AWE_PLUGIN_LOADER_SUCCESS	Operation succeeded.
AWE_PLUGIN_LOADER_UNINITIALIZED	Plugin loader is uninitialized.
AWE_PLUGIN_LOADER_ALREADY_INITIALIZED	Attempting to initialize the plugin loader after it has already been initialized.
AWE_PLUGIN_LOADER_MISSING_METHOD	A required method is missing after applying overrides (this can happen when the library was not compiled with a default for a given method).
AWE_PLUGIN_LOADER_ALLOCATION_FAILED	Memory allocation failed.
AWE_PLUGIN_LOADER_INVALID_INDEX	Plugin index is out of range.
AWE_PLUGIN_LOADER_DL_OPEN_FAILED	Failed to open the dynamic library.
AWE_PLUGIN_LOADER_DL_SYMBOL_NOT_FOUND	Initialization function was not found in the plugin library.
AWE_PLUGIN_LOADER_DL_INTERNAL_FAILURE	The plugin library's initialization function returned null.

Function Documentation

awe_PluginLoader_init()

enum awe_PluginLoader_Status awe_PluginLoader_init

(

size_t

reserved_count

)

Initialize the plugin loader.

This function (or awe_PluginLoader_initWithMethods) must be called before the plugin loader can be used. Will error if called while the loader is already initialized, but doing so is otherwise safe.

Parameters

reserved_count

The number of plugin entries to preallocate.

Returns

AWE_PLUGIN_LOADER_SUCCESS or a status code indicating an error.

awe_PluginLoader_initWithMethods()

enum awe_PluginLoader_Status awe_PluginLoader_initWithMethods	(	size_t	reserved_count,
		const awe_PluginLoaderMethods *const	overrides
	)

Initialize the plugin loader with a set of override callbacks.

Like awe_PluginLoader_init, except it will use functions provided via overrides instead of the defaults.

Parameters

	reserved_count	The number of plugin entries to preallocate.
[in]	overrides	Callbacks which replace system functions used by the plugin loader. Note that the loader does not take ownership of this pointer. If it is dynamically allocated, it must be freed by the caller. However, it also does not need to outlive this function call, as the loader's initialization method maintains a copy internally. Consequently, it is impossible to change the loader's internal callback table without reinitializing it.

Returns

AWE_PLUGIN_LOADER_SUCCESS or a status code indicating an error.

Examples

Libtester.c.

awe_PluginLoader_load()

enum awe_PluginLoader_Status awe_PluginLoader_load	(	const AWEPlugin **	plugin,
		const char *	file
	)

Load a plugin library.

Open a dynamic library and attempt to load it using its entrypoint method. The load operation itself is idempotent, meaning once a plugin has been loaded this method will output the same cached value until the loader is freed. It is thus safe to call this method more than once without reinitializing the loader, though each call will increase the reference count for the given plugin. Calling this method without first initializing the loader will return an error status, but is otherwise safe.

Parameters

[out]	plugin	If successful, the function will output a pointer to a valid AWEPlugin struct. Otherwise, it will be set to NULL.
[in]	file	A dynamic library to be loaded. The details of what exactly constitutes a valid file identifier may vary across platform, but generally speaking this should be a valid argument to dlopen.

Returns

AWE_PLUGIN_LOADER_SUCCESS or a status code indicating an error.

Examples

Libtester.c.

awe_PluginLoader_unload()

enum awe_PluginLoader_Status awe_PluginLoader_unload

(

const char *

file

)

Unload a plugin library.

Decreases the reference count corresponding to the provided plugin file name. If it reaches zero, the plugin library is unloaded and all associated memory is freed. Caller is responsible for ensuring that the plugin's functionality is no longer in use before calling this method.

It is typically unnecessary to explicitly unload plugin libraries, as awe_PluginLoader_free will automatically do the same operation for all libraries which are loaded at the time it is called.

Parameters

[in]

file

A dynamic library to be unloaded. Must exactly match the argument given to awe_PluginLoader_load.

Returns

AWE_PLUGIN_LOADER_SUCCESS or a status code indicating an error.

See also

awe_PluginLoader_free

awe_PluginLoader_loadWithNamespacePrefix()

enum awe_PluginLoader_Status awe_PluginLoader_loadWithNamespacePrefix	(	const AWEPlugin **	plugin,
		const char *	file,
		const char *	prefix
	)

Load a plugin library with a namespaced entrypoint name.

Open a dynamic library and attempt to load it using its entrypoint method. Provide a prefix string which will be prepended to symbol lookups.

Parameters

[out]	plugin	If successful, the function will output a pointer to a valid AWEPlugin struct. Otherwise, it will be set to NULL.
[in]	file	A dynamic library to be loaded. The details of what exactly constitutes a valid file identifier may vary across platform, but generally speaking this should be a valid argument to dlopen.
[in]	prefix	A null-terminated string which will be prepended to the name of the entrypoint symbol when we search for it in the plugin library.

Returns

AWE_PLUGIN_LOADER_SUCCESS or a status code indicating an error.

See also

awe_PluginLoader_load

awe_PluginLoader_loadWithEntrypoint()

enum awe_PluginLoader_Status awe_PluginLoader_loadWithEntrypoint	(	const AWEPlugin **	plugin,
		const char *	file,
		const char *	entrypoint
	)

Load a plugin library with a custom entrypoint name.

Open a dynamic library and attempt to load it using its entrypoint method, whose name is provided by the caller. Note that this does not apply to the fallback "legacy" plugin ABI.

Parameters

[out]	plugin	If successful, the function will output a pointer to a valid AWEPlugin struct. Otherwise, it will be set to NULL.
[in]	file	A dynamic library to be loaded. The details of what exactly constitutes a valid file identifier may vary across platform, but generally speaking this should be a valid argument to dlopen.
[in]	entrypoint	A null-terminated string which will be used to look up the entrypoint symbol in the plugin library.

Returns

AWE_PLUGIN_LOADER_SUCCESS or a status code indicating an error.

See also

awe_PluginLoader_load

awe_PluginLoader_count()

size_t awe_PluginLoader_count

(

)

Get the number of currently loaded plugins.

Returns

The loaded plugin count, or zero if the PluginLoader is uninitialized.

See also

awe_PluginLoader_get

Examples

Libtester.c.

awe_PluginLoader_get()

enum awe_PluginLoader_Status awe_PluginLoader_get	(	const AWEPlugin **	plugin,
		size_t	index
	)

Retrieve a loaded plugin by index.

Indices may change during the lifetime of the loader. This method is typically intended to be used in the context of a loop iterating over all loaded plugins. In all other contexts, awe_PluginLoader_find should be prefered as a means to access plugins.

Parameters

[out]	plugin	If successful, the function will output a pointer to a valid AWEPlugin struct. Otherwise, it will be set to NULL.
	index	The index of the desired plugin in the loader's internal plugin list.

Returns

AWE_PLUGIN_LOADER_SUCCESS or a status code indicating an error.

See also

awe_PluginLoader_count

awe_PluginLoader_load

awe_PluginLoader_find

Examples

Libtester.c.

awe_PluginLoader_find()

enum awe_PluginLoader_Status awe_PluginLoader_find	(	const AWEPlugin **	plugin,
		const char *	file
	)

Retrieve a loaded plugin by file name.

Iterate through the list of loaded plugins, returning the first file name match. This method does not do any processing to the file name. It must exactly match the value which was provided to awe_PluginLoader_load.

Parameters

[out]	plugin	If successful, the function will output a pointer to a valid AWEPlugin struct. Otherwise, it will be set to NULL.
	file	The file name of the desired plugin. It must exactly match the value which was provided to awe_PluginLoader_load.

Returns

AWE_PLUGIN_LOADER_SUCCESS or a status code indicating an error.

See also

awe_PluginLoader_load

awe_PluginLoader_get

awe_PluginLoader_free()

void awe_PluginLoader_free

(

)

Clean up the plugin loader.

Invalidates all loaded AWEPlugin handles.

Close all plugin libraries and free internal dynamic memory used by the loader. Once the loader has been freed, it may be reinitialized if so desired. However, after calling this function, all existing AWEPlugin handles may point to freed or otherwise inaccessible memory. The caller is responsible for making sure they are not used. The simplest way to guarantee this will typically be to initialize the loader once at the start of main and free it just before the process exits.

See also

awe_PluginLoader_init

awe_PluginLoader_initWithMethods

Examples

Libtester.c.

awe_PluginLoader_statusToString()

const char * awe_PluginLoader_statusToString

(

const enum awe_PluginLoader_Status

status

)

Get a description of the given status.

Parameters

status

A status code.

Returns

Static null-terminated string describing the status code.

See also

awe_PluginLoader_Status

Examples

Libtester.c.