IPlugIn Class Reference

#include <IPlugIn.h>

Inheritance diagram for IPlugIn:

Public Types
enum	ThreadingPolicy { kUnknownThreadingPolicy =0, kMainThreadOnly =1, kMultipleThreads =2 }

Public Member Functions
virtual bool16	Load (ISession *theSession)=0
virtual bool16	Unload ()=0
virtual bool16	LoadAtStartup ()=0
virtual bool16	CanUnload () const =0
virtual void	FixUpData (IDocument *doc)=0
virtual PluginID	GetPluginID () const =0
virtual void	SetPluginID (PluginID pluginID)=0
virtual IDFile	GetResourceFile () const =0
virtual void	LoadFactories (PluginID ownerComponent, ISession *theSession)=0

Detailed Description

Every plug-in must supply an implementation of IPlugIn, although often a 

plug-in may choose to use the base class PlugIn if there's no need to

override anything. IPlugIn is the main entry point to the plug-in.



THIS IS NOT A STANDARD BOSS INTERFACE. It does not inherit from IPMUnknown.

It is a regular C++ object.



If your plug-in has no need to override anything in IPluIn, it can

just supply the following code:

#include "PlugIn.h"

#include "GetPlugIn.h"

static PlugIn gPlugIn;

// This is the main entry point from the application to the plug-in.

// The application calls this function when the plug-in is installed 

// or loaded. This function is called by name, so it must be called 

// GetPlugIn, and defined as C linkage.

IPlugIn *GetPlugIn()

{

    return 

}



To override the default IPlugIn implementation with your own,

just have your GetPlugIn function return an IPlugIn that you

supply. Your IPlugIn should inherit from PlugIn. Here's an

example:

class MyPlugin : public PlugIn

{

public:

    virtual bool16 CanUnload();

};

static MyPlugin gPlugIn;

IPlugIn *GetPlugIn()

{

    return 

}

Member Enumeration Documentation

enum IPlugIn::ThreadingPolicy

Enumerates the different types of thread support a plugin can have

Member Function Documentation

virtual bool16 IPlugIn::CanUnload ( ) const

pure virtual

The plugin is asked whether it is currently OK to unload it. Under rare circumstances, your plug-in may be asked to Unload if there are certain types of system errors on the Mac. If you want to override this and prevent the unload, you need to override CanUnload to return false.

Returns

bool16 kTrue to proceed with the unload, kFalse to prevent unloading

Implemented in PlugIn.

virtual void IPlugIn::FixUpData ( IDocument *  doc )

pure virtual

FixUpData is called when the application opens a document which contains data that was originally supplied by this plug-in, and was subsequently edited during a session when the plug-in was not loaded. This is a chance for the plugin to update or remove any data that became stale due to these changes.

Parameters

IDocument*

document being opened

Implemented in PlugIn, and PstLstPlugIn.

virtual PluginID IPlugIn::GetPluginID ( ) const

pure virtual

GetPlugIn()->GetPluginID() can be called at runtime to get the pluginID of the currently executing plugin

Returns

PluginID of the plugin. Please use this instead of calling GetResourceFile() to create a ResourceEnabler.

Implemented in PlugIn.

virtual IDFile IPlugIn::GetResourceFile ( ) const

pure virtual

Internal Use Only

Implemented in PlugIn.

virtual bool16 IPlugIn::Load ( ISession *  theSession )

pure virtual

Called when the application loads the plug-in. Typically a plug-in that needs to do some action at startup should use IStartupShutdownService. The plug-in should override Load only if there is some global state which, if missing, would cause the plug-in to be useless.

Parameters

theSession

pointer to the global session, which is the root of the object hierarchy.

Returns

bool16 kTrue if plug-in loaded OK, false otherwise.

Implemented in PlugIn.

virtual bool16 IPlugIn::LoadAtStartup ( )

pure virtual

Returns kTrue if the plugin needs to get loaded on every startup. Most plug-ins are not loaded at startup, they only get loaded the first time they are accessed. You may override this behavior and force the plug-in to load at startup by returning true. Note that this will introduce a performance penalty to the user, since startup will be slower even the user never needed the plug-in.

Returns

bool16 kTrue to force plug-in to load at startup.

Implemented in PlugIn.

virtual void IPlugIn::LoadFactories ( PluginID  ownerComponent, ISession *  theSession  )

pure virtual

Internal Use Only

Implemented in PlugIn.

virtual void IPlugIn::SetPluginID ( PluginID  pluginID )

pure virtual

Internal Use Only

Implemented in PlugIn.

virtual bool16 IPlugIn::Unload ( )

pure virtual

Called when the application is shutting down. Typically a plug-in that needs to do some action at shutdown should use IStartupShutdownService. Under rare circumstances, your plug-in may be asked to Unload if there are certain types of system errors on the Mac. If you want to override this and prevent the unload, you need to override CanUnload to return false.

Returns

bool16 kTrue

Implemented in PlugIn.