Plug-In Basics


GetPluginFactory

From the host's point of view a Plug-In Module is a factory which can create a certain kind of object(s). The interface IPluginFactory provides methods to get information about the classes exported by the Plug-In and a mechanism to create instances of these classes.

The host calls GetPluginFactory to get a pointer to an IPluginFactory object. The SDK already implements a Plug-In factory (see CPluginFactory in pluginfactory.h) that should meet your requirements. All you have to do is to register your class information once with CPluginFactory::registerClass.

PLUGIN_API IPluginFactory* GetPluginFactory ()
{
	if(!gPluginFactory)
	{
		gPluginFactory = new CPluginFactory (factoryInfo);

		//register classes here...
		gPluginFactory->registerClass (pluginClass, myCreateFunc, 0);
	}
	else
		gPluginFactory->addRef ();

	return gPluginFactory;
}

To get this code compiled, you need factory information of type PFactoryInfo, class information of type PClassInfo (both declared in ipluginbase.h) and a function to create the class instance.

Member Description
PClassInfo::cid Class identifier used in IPluginFactory::createInstance. Every class implementation must have its own identifier. On Windows you can use e.g. the Visual Studio Tool Guidgen.exe to generate it.
PClassInfo::cardinality Currently ignored, you should set this to PClassInfo::kManyInstances.
PClassInfo::category Category string of the class, e.g. kMidiModuleClass for MIDI effects,...
The host relies on the category given here and expects e.g. an object with an IMidiEffect interface if the string is kMidiModuleClass.
PClassInfo::name Class name visible to the user e.g. "My first Plug-In"

The create function has to look something like this:

FUnknown* myCreateFunc (void* context)
{
	return (IPluginBase*)new CMyPlugin ();
}

The context value is the last parameter passed to CPluginFactory::registerClass. It has no pre-defined meaning, you can use it for whatever you want.


Exporting GetPluginFactory

To make the function GetPluginFactory "visible" to the host application, it has to be exported.

In Microsoft® Visual C++ you need to add a DEF-File to your project, which looks something like this:

LIBRARY MyPluginName
EXPORTS
    GetPluginFactory


Host example

The host application will handle your Plug-In something like this (some code is Windows-specific!):

HMODULE hModule = LoadLibrary ("SomePlugin.dll");
if(hModule)
{
	GetFactoryProc proc = (GetFactoryProc)GetProcAddress (hModule, "GetPluginFactory");

	IPluginFactory* factory = proc ? proc () : 0;
	if(factory)
	{
		for(long i = 0; i < factory->countClasses (); i++)
		{
			PClassInfo ci;
			factory->getClassInfo (i, &ci);

			FUnknown* obj;
			factory->createInstance (ci.cid, FUnknown::iid, (void**)&obj);
			...
			obj->release ();
		}

		factory->release ();
	}

	FreeLibrary (hModule);
}


IPluginFactory

Inheritance: FUnknown <- IPluginFactory
Include File:  ipluginbase.h

This interface provides methods to get information about classes exported by a Plug-In Module, and a mechanism to create instances of these classes.

Methods:


IPluginFactory::getFactoryInfo

tresult PLUGIN_API getFactoryInfo (PFactoryInfo* info);

Fill a PFactoryInfo structure with information about the Plug-In vendor.

PFactoryInfo Flags:

kPluginClassesDiscardable The number of exported classes can change each time the Module is loaded. If this flag is set, the host does not cache class information. This leads to a longer startup time because the host always has to load the Module to get the current class information.


IPluginFactory::countClasses

long PLUGIN_API countClasses ();

Returns the number of exported classes.

If you are using the CPluginFactory implementation provided by the SDK, it returns the number of classes you registered with CPluginFactory::registerClass.


IPluginFactory::getClassInfo

tresult PLUGIN_API getClassInfo (long index, PClassInfo* info)

Fill a PClassInfo structure with information about the class at the specified index.


IPluginFactory::createInstance

tresult PLUGIN_API createInstance (const char* cid, const char* iid, void** obj);

Create an new class instance.

Parameters:

cid Class Identifier of the class instance to be created (see PClassInfo::cid)
iid Unique Identifier of the requested interface
obj Variable which receives a pointer to the newly created object.


IPluginBase

Inheritance: FUnknown <- IPluginBase
Include File:  ipluginbase.h

All exported Plug-In classes are derived from IPluginBase in some way. The interface provides two methods:

Methods:


IPluginBase::initialize

tresult PLUGIN_API initialize (FUnknown* context);

The Plug-In receives a context in which it will run. The context can always be queried for at least the following interfaces:

Remarks:

Extensive memory allocations etc. should be performed in this method rather than in the class constructor!
If the method does NOT return kResultOk, the object is released immediately. In this case terminate is not called!


IPluginBase::terminate

tresult PLUGIN_API terminate ()

This method will be called immediately before the Plug-In is destroyed. You have to release all references to any host application interfaces.



Last Modified: