BASS.NET API for the Un4seen BASS Audio Library

BassBASS_PluginLoad Method

BASS.NET API for the Un4seen BASS Audio Library
Plugs on "add-on" into the standard stream and sample creation functions.

This overload implements the Unicode version for the file name.

Namespace:  Un4seen.Bass
Assembly:  Bass.Net (in Bass.Net.dll) Version: 2.4.17.5
Syntax

public static int BASS_PluginLoad(
	string file
)

Parameters

file
Type: SystemString
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.

Return Value

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

There are 2 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(String, Int64, Int64, BASSFlag), BASS_StreamCreateURL(String, Int32, BASSFlag, DOWNLOADPROC, IntPtr), and BASS_StreamCreateFileUser(BASSStreamSystem, BASSFlag, BASS_FILEPROCS, IntPtr). 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(String, Int64, Int32, Int32, BASSFlag).

Information on what file formats a plugin supports is available via the BASS_PluginGetInfo(Int32) 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.

Note: Only stream/music add-ons are loaded (e.g. bass_fx.dll or bassmix.dll are NOT loaded).

Platform-specific:

Dynamic libraries are not permitted on iOS, so add-ons are provided as static libraries instead, which means this function has to work a little differently. The add-on needs to be linked into the executable, and a "plugin" symbol declared and passed to this function (instead of a filename).

ERROR CODEDescription
BASS_ERROR_FILEOPENThe file could not be opened.
BASS_ERROR_FILEFORMThe file is not a plugin.
BASS_ERROR_ALREADYThe file is already plugged in.
BASS_ERROR_VERSIONThe 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.

Examples

Add-On residing in same directory:
// load the FLAC add-on
int pluginFlac = Bass.BASS_PluginLoad("bassflac.dll");
...
// use the add-on
int stream = Bass.BASS_StreamCreateFile("file.flac", 0, 0, BASSFlag.BASS_DEFAULT);
...
// un-load the FLAC add-on
Bass.BASS_PluginFree(pluginFlac);
See Also

Reference