Loading a Plugin
Module: AudioWeaver Plugins
Using the AudioWeaver Plugin API to load plugin libraries. More...
Classes
| Name | |
|---|---|
| struct | _awe_PluginLoaderMethods Method table to provide overrides to awe_PluginLoader_initWithMethods. |
Types
| Name | |
|---|---|
| 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, AWE_PLUGIN_LOADER_LIBRARY_FILE_NAME_TOO_LONG = -9} Possible statuses which may be returned by plugin loader API functions. |
| typedef struct _awe_PluginLoaderMethods | awe_PluginLoaderMethods Method table to provide overrides to awe_PluginLoader_initWithMethods. |
Functions
| Name | |
|---|---|
| enum awe_PluginLoader_Status | awe_PluginLoader_init(size_t reserved_count) Initialize the plugin loader. |
| enum awe_PluginLoader_Status | awe_PluginLoader_initWithMethods(size_t reserved_count, const awe_PluginLoaderMethods *const overrides) override Initialize the plugin loader with a set of override callbacks. |
| enum awe_PluginLoader_Status | awe_PluginLoader_load(const AWEPlugin ** plugin, const char * file) Load a plugin library. |
| enum awe_PluginLoader_Status | awe_PluginLoader_unload(const char * file) Unload a plugin library. |
| 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. |
| 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. |
| size_t | awe_PluginLoader_count() Get the number of currently loaded plugins. |
| enum awe_PluginLoader_Status | awe_PluginLoader_get(const AWEPlugin ** plugin, size_t index) Retrieve a loaded plugin by index. |
| enum awe_PluginLoader_Status | awe_PluginLoader_find(const AWEPlugin ** plugin, const char * file) Retrieve a loaded plugin by file name. |
| void | awe_PluginLoader_free() Clean up the plugin loader. |
| const char * | awe_PluginLoader_statusToString(const enum awe_PluginLoader_Status status) Get a description of the given status. |
Defines
| Name | |
|---|---|
| AWE_PLUGIN_LOADER_MAX_PATH_LENGTH Maximum length for library paths passed to awe_PluginLoader_load. |
Detailed Description
Using the AudioWeaver Plugin API to load plugin libraries.
For information on how to create a plugin, see Creating a Plugin.
Types Documentation
enum awe_PluginLoader_Status
| Enumerator | Value | Description |
|---|---|---|
| AWE_PLUGIN_LOADER_SUCCESS | 0 | Operation succeeded. |
| AWE_PLUGIN_LOADER_UNINITIALIZED | -1 | Plugin loader is uninitialized. |
| AWE_PLUGIN_LOADER_ALREADY_INITIALIZED | -2 | Attempting to initialize the plugin loader after it has already been initialized. |
| AWE_PLUGIN_LOADER_MISSING_METHOD | -3 | 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 | -4 | Memory allocation failed. |
| AWE_PLUGIN_LOADER_INVALID_INDEX | -5 | Plugin index is out of range. |
| AWE_PLUGIN_LOADER_DL_OPEN_FAILED | -6 | Failed to open the dynamic library. |
| AWE_PLUGIN_LOADER_DL_SYMBOL_NOT_FOUND | -7 | Initialization function was not found in the plugin library. |
| AWE_PLUGIN_LOADER_DL_INTERNAL_FAILURE | -8 | The plugin library's initialization function returned null. |
| AWE_PLUGIN_LOADER_LIBRARY_FILE_NAME_TOO_LONG | -9 | The plugin loader was provided with a file name which is longer than AWE_PLUGIN_LOADER_MAX_PATH_LENGTH. |
Possible statuses which may be returned by plugin loader API functions.
typedef 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.
Functions Documentation
function awe_PluginLoader_init
enum awe_PluginLoader_Status awe_PluginLoader_init(
size_t reserved_count
)
Initialize the plugin loader.
Parameters:
- reserved_count The number of plugin entries to preallocate.
Return: AWE_PLUGIN_LOADER_SUCCESS or a status code indicating an error.
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.
function awe_PluginLoader_initWithMethods
enum awe_PluginLoader_Status awe_PluginLoader_initWithMethods(
size_t reserved_count,
const awe_PluginLoaderMethods *const overrides
) override
Initialize the plugin loader with a set of override callbacks.
Parameters:
- reserved_count The number of plugin entries to preallocate.
- 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.
Return: AWE_PLUGIN_LOADER_SUCCESS or a status code indicating an error.
Like awe_PluginLoader_init, except it will use functions provided via overrides instead of the defaults.
function awe_PluginLoader_load
enum awe_PluginLoader_Status awe_PluginLoader_load(
const AWEPlugin ** plugin,
const char * file
)
Load a plugin library.
Parameters:
- plugin If successful, the function will output a pointer to a valid AWEPlugin struct. Otherwise, it will be set to NULL.
- 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.
Return: AWE_PLUGIN_LOADER_SUCCESS or a status code indicating an error.
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.
function awe_PluginLoader_unload
enum awe_PluginLoader_Status awe_PluginLoader_unload(
const char * file
)
Unload a plugin library.
Parameters:
- file A dynamic library to be unloaded. Must exactly match the argument given to awe_PluginLoader_load.
See: awe_PluginLoader_free
Return: AWE_PLUGIN_LOADER_SUCCESS or a status code indicating an error.
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.
function 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.
Parameters:
- plugin If successful, the function will output a pointer to a valid AWEPlugin struct. Otherwise, it will be set to NULL.
- 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.
- 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.
See: awe_PluginLoader_load
Return: AWE_PLUGIN_LOADER_SUCCESS or a status code indicating an error.
Open a dynamic library and attempt to load it using its entrypoint method. Provide a prefix string which will be prepended to symbol lookups.
function 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.
Parameters:
- plugin If successful, the function will output a pointer to a valid AWEPlugin struct. Otherwise, it will be set to NULL.
- 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.
- entrypoint A null-terminated string which will be used to look up the entrypoint symbol in the plugin library.
See: awe_PluginLoader_load
Return: AWE_PLUGIN_LOADER_SUCCESS or a status code indicating an error.
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.
function awe_PluginLoader_count
size_t awe_PluginLoader_count()
Get the number of currently loaded plugins.
See: awe_PluginLoader_get
Return: The loaded plugin count, or zero if the PluginLoader is uninitialized.
function awe_PluginLoader_get
enum awe_PluginLoader_Status awe_PluginLoader_get(
const AWEPlugin ** plugin,
size_t index
)
Retrieve a loaded plugin by index.
Parameters:
- 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.
See:
- awe_PluginLoader_count
- awe_PluginLoader_load
- awe_PluginLoader_find
Return: AWE_PLUGIN_LOADER_SUCCESS or a status code indicating an error.
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.
function awe_PluginLoader_find
enum awe_PluginLoader_Status awe_PluginLoader_find(
const AWEPlugin ** plugin,
const char * file
)
Retrieve a loaded plugin by file name.
Parameters:
- 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.
See:
- awe_PluginLoader_load
- awe_PluginLoader_get
Return: AWE_PLUGIN_LOADER_SUCCESS or a status code indicating an error.
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.
function awe_PluginLoader_free
void awe_PluginLoader_free()
Clean up the plugin loader.
See:
- awe_PluginLoader_init
- awe_PluginLoader_initWithMethods
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.
function 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.
See: awe_PluginLoader_Status
Return: Static null-terminated string describing the status code.
Macros Documentation
define AWE_PLUGIN_LOADER_MAX_PATH_LENGTH
#define AWE_PLUGIN_LOADER_MAX_PATH_LENGTH (1024)
Maximum length for library paths passed to awe_PluginLoader_load.
Updated on 2026-02-10 at 15:44:29 -0500