BASS_PluginLoad

Plugs an "add-on" into the standard stream and sample creation functions.

HPLUGIN BASS_PluginLoad(
    char *file,
    DWORD flags
);

Parameters

file

Name or filename of the add-on/plugin. If only a name is provided then the platform's standard library prefix and suffix/extension will be added to it.

flags

A combination of these flags.

BASS_UNICODE	file is in UTF-16 form. Otherwise it is ANSI on Windows and UTF-8 on other platforms.
BASS_PLUGIN_PROC	file is a pointer to a "plugin" symbol rather than a name or filename. This should be used with old iOS add-ons that are in static library form.

Return value

If successful, the loaded plugin's handle is returned, else 0 is returned. Use BASS_ErrorGetCode to get the error code.

Error codes

BASS_ERROR_FILEOPEN	The file could not be opened.
BASS_ERROR_FILEFORM	The file is not a plugin.
BASS_ERROR_VERSION	The plugin requires a different BASS version. Due to the use of the "stdcall" calling-convention, and so risk of stack faults from unexpected API differences, an add-on won't load at all on Windows if the BASS version is unsupported, and a BASS_ERROR_FILEFORM error will be generated instead of this.
BASS_ERROR_ALREADY	The plugin is already loaded.

Remarks

There are two ways in which add-ons can provide support for additional formats. They can provide dedicated functions to create streams of the specific format(s) they support and/or they can plug into the standard stream creation functions: BASS_StreamCreateFile, BASS_StreamCreateURL, and BASS_StreamCreateFileUser. This function enables the latter method. Both methods can be used side by side. The obvious advantage of the plugin system is convenience, while the dedicated functions can provide extra options that are not possible via the shared function interfaces. See an add-on's documentation for more specific details on it.

As well as the stream creation functions, plugins also add their additional format support to BASS_SampleLoad.

Information on what file formats a plugin supports is available via the BASS_PluginGetInfo function.

When using multiple plugins, the stream/sample creation functions will try each of them in the order that they were loaded via this function, until one that accepts the file is found.

When an add-on is already loaded (eg. if you are using functions from it), the plugin system will use the same instance (the reference count will just be incremented); there will not be 2 copies of the add-on in memory.

Platform-specific

When no path is specified, Windows' normal library search path will be used, while the BASS library's path (as in the BASS_CONFIG_FILENAME value) will be used on other platforms.

On iOS prior to BASS 2.4.17, add-ons were static libraries rather than dynamic libraries and they had to be loaded slightly differently, by providing a "plugin" symbol from the add-on instead of its filename. If wanted, those old add-ons can still be used now with the BASS_PLUGIN_PROC flag. See the example below.

Example

Plugin the BASSFLAC add-on.

BASS_PluginLoad("bassflac", 0);

Plugin an old static library BASSFLAC add-on on iOS.

extern void BASSFLACplugin;
BASS_PluginLoad(&BASSFLACplugin, BASS_PLUGIN_PROC);