SPAccess.h File Reference

#include "SPTypes.h"
#include "SPPlugs.h"
#include "SPMData.h"
#import <CoreServices/CoreServices.h>
#include "AIWinDef.h"
#include "SPHeaderBegin.h"
#include "SPErrorCodes.h"
#include "SPHeaderEnd.h"

Go to the source code of this file.

Classes
struct	SPMacResChain
	Resource chain access information on Mac OS. More...
struct	SPPlatformAccessInfo
	Access information for the resource chain on Mac OS, or library information on Windows. More...
struct	SPAccessMessage
	Message sent with the kSPAccessCaller. More...
struct	SPAccessSuite
	This suite is used to load and unload plug-ins. More...
Defines
#define	kSPAccessSuite   "SP Access Suite"
	Plug-in Access suite name.
#define	kSPAccessSuiteVersion   3
	Plug-in Access suite name.
#define	kSPAccessCaller   "SP Access"
	The SPAccessSuite sends a reload message (kSPAccessReloadSelector) to a plug-in when it has just been loaded, and an unload message (kSPAccessUnloadSelector) when it is about to be unloaded.
#define	kSPAccessReloadSelector   "Reload"
	The first message a plug-in receives on startup (whether loaded or reloaded).
#define	kSPAccessUnloadSelector   "Unload"
	The first message a plug-in receives before being unloaded.
#define	kSPFlushAccessType   "SP Flush Access"
	The name of the object that the SPAccessSuite caches, which can be purged when caches are flushed.
Typedefs
typedef SPAPI SPErr(*	SPEntry )(const char *caller, const char *selector, void *message)
	Prototype for a plug-in entry point, which receives messages from the application or other plug-ins.
typedef struct SPAccess *	SPAccessRef
	A plug-in access object, used with the SPAccessSuite to make calls to a plug-in.
typedef short	FSIORefNum
typedef SPMacResChain *	SPPlatformAccessRef
	Resource chain access information on Mac OS.
Enumerations
enum	SPAccessPoint { kStartup = 0, kRuntime, kShutdown, kTerminal }
	Sent in the SPAccessMessage to identify when an access call was made. More...
Functions
SPAPI SPErr	SPAcquirePlugin (SPPluginRef plugin, SPAccessRef *access)
	Internal.
SPAPI SPErr	SPReleasePlugin (SPAccessRef access)
	Internal.
SPAPI SPErr	SPGetPluginAccess (SPPluginRef plugin, SPAccessRef *access)
	Internal.
SPAPI SPErr	SPGetAccessPlugin (SPAccessRef access, SPPluginRef *plugin)
	Internal.
SPAPI SPErr	SPGetAccessEntry (SPAccessRef access, SPEntry *entry)
	Internal.
SPAPI SPErr	SPGetAccessCount (SPAccessRef access, ai::int32 *count)
	Internal.
SPAPI SPErr	SPGetAccessInfo (SPAccessRef access, SPPlatformAccessInfo *info)
	Internal.
SPAPI SPErr	SPGetPluginResourceAccess (SPPluginRef plugin, SPPlatformAccessRef *resourceAccess)
	Internal.
SPAPI SPErr	SPSetPluginResourceAccess (SPPluginRef plugin, SPPlatformAccessRef resourceAccess)
	Internal.
SPAPI SPErr	SPCallPlugin (SPAccessRef access, const char *caller, const char *selector, void *message, SPErr *result)
	Internal.
SPAPI SPErr	SPGetCurrentPlugin (SPPluginRef *plugin)
	Internal.
SPAPI SPErr	SPSetCurrentPlugin (SPPluginRef plugin)
	Internal.

---

Define Documentation

#define kSPAccessSuite   "SP Access Suite"

Plug-in Access suite name.

#define kSPAccessSuiteVersion   3

Plug-in Access suite name.

#define kSPFlushAccessType   "SP Flush Access"

The name of the object that the SPAccessSuite caches, which can be purged when caches are flushed.

During a cache flush, if this is the type sent to the SPFlushCachesProc, it can make calls to the Access suite to collect information about the access object before deciding to purge it or not.

For example, this purges filter plug-ins before window plug-ins:

long myFlushCachesProc( const char *type, void *data, SPErr *error ) {
long flush = TRUE;
if ( strcmp( type, kSPFlushAccessType ) == 0 ) {
        SPAccessRef access = data;
        SPPluginRef plugin = sAccess->GetAccessPlugin( access, error );
        fail( error );
                switch ( myPluginType( plugin ) ) {
                        case kMyFilterPlugin:
                                if ( gPurgeLevel < kFilterPurgeLevel )
                                        flush = FALSE;
                                break;
                        case kMyWindowPlugin:
                                if ( gPurgeLevel < kWindowPurgeLevel )
                                        flush = FALSE;
                                break;
                }
        }
        return flush;
}

---

Typedef Documentation

typedef short FSIORefNum

typedef struct SPAccess* SPAccessRef

A plug-in access object, used with the SPAccessSuite to make calls to a plug-in.

These objects are reference counted. The count is incremented when you acquire the object using SPAccessSuite::AcquirePlugin() and decremented when you release it with SPAccessSuite::ReleasePlugin(), so you must be careful to balance these calls. The object is automatically created and the plug-in loaded if necessary, and the object is destroyed and the plug-in unloaded when the reference count is 0.

typedef SPAPI SPErr(* SPEntry)(const char *caller, const char *selector, void *message)

Prototype for a plug-in entry point, which receives messages from the application or other plug-ins.

Parameters:

	caller	The caller, which identifies what suite or subsystem made the call. See Plug-in Callers.
	selector	The specific event that triggered the call. See Plug-in Selectors.
	message	The message data, whose type depends on the specific event.

typedef HINSTANCE SPPlatformAccessRef

Resource chain access information on Mac OS.

Plug-in library handle on Windows.

---

Enumeration Type Documentation

enum SPAccessPoint

Sent in the SPAccessMessage to identify when an access call was made.

Use to distinguish a start-up load from a run-time load or reload, and a run-time unload from a shut-down unload.

Enumerator:

kStartup	The receiving plug-in has been loaded at application startup, and not yet initialized. Sent with the kSPAccessReloadSelector.
kRuntime	The receiving plug-in has been loaded programmatically while the application is running, and has already been initialized. Sent with the kSPAccessReloadSelector and the kSPAccessUnloadSelector.
kShutdown	The receiving plug-in is about to be unloaded after being shut down. Sent with the kSPAccessUnloadSelector.
kTerminal	The receiving plug-in has a non-zero access count and the application is shutting down. Sent with the kSPAccessUnloadSelector. If the plug-in has acquired itself in order to remain in memory, it should not free any resources and not acquire others when this call is received.

---

Function Documentation

SPAPI SPErr SPAcquirePlugin	(	SPPluginRef	plugin,
		SPAccessRef *	access
	)

Internal.

SPAPI SPErr SPCallPlugin	(	SPAccessRef	access,
		const char *	caller,
		const char *	selector,
		void *	message,
		SPErr *	result
	)

Internal.

SPAPI SPErr SPGetAccessCount	(	SPAccessRef	access,
		ai::int32 *	count
	)

Internal.

SPAPI SPErr SPGetAccessEntry	(	SPAccessRef	access,
		SPEntry *	entry
	)

Internal.

SPAPI SPErr SPGetAccessInfo	(	SPAccessRef	access,
		SPPlatformAccessInfo *	info
	)

Internal.

SPAPI SPErr SPGetAccessPlugin	(	SPAccessRef	access,
		SPPluginRef *	plugin
	)

Internal.

SPAPI SPErr SPGetCurrentPlugin

(

SPPluginRef *

plugin

)

Internal.

SPAPI SPErr SPGetPluginAccess	(	SPPluginRef	plugin,
		SPAccessRef *	access
	)

Internal.

SPAPI SPErr SPGetPluginResourceAccess	(	SPPluginRef	plugin,
		SPPlatformAccessRef *	resourceAccess
	)

Internal.

SPAPI SPErr SPReleasePlugin

(

SPAccessRef

access

)

Internal.

SPAPI SPErr SPSetCurrentPlugin

(

SPPluginRef

plugin

)

Internal.

SPAPI SPErr SPSetPluginResourceAccess	(	SPPluginRef	plugin,
		SPPlatformAccessRef	resourceAccess
	)

Internal.