SPAccessSuite Struct Reference
[API Suite List]

This suite is used to load and unload plug-ins. More...

#include <SPAccess.h>

Public Attributes
SPAPI SPErr(*	AcquirePlugin )(SPPluginRef plugin, SPAccessRef *access)
	Loads a plug-in if necessary, and prepares it to be called.
SPAPI SPErr(*	ReleasePlugin )(SPAccessRef access)
	Decrements the reference count of an accessor object.
SPAPI SPErr(*	GetPluginAccess )(SPPluginRef plugin, SPAccessRef *access)
	Retrieves the accessor object for a plug-in.
SPAPI SPErr(*	GetAccessPlugin )(SPAccessRef access, SPPluginRef *plugin)
	Retrieves the plug-in for an accessor.
SPAPI SPErr(*	GetAccessEntry )(SPAccessRef access, SPEntry *entry)
	Retrieves the entry point of a plug-in accessor.
SPAPI SPErr(*	GetAccessCount )(SPAccessRef access, ai::int32 *count)
	Retrieves the current reference count of an accessor object.
SPAPI SPErr(*	GetAccessInfo )(SPAccessRef access, SPPlatformAccessInfo *info)
	Retrieves the platform-specific resource access information of a plug-in accessor.
SPAPI SPErr(*	GetPluginResourceAccess )(SPPluginRef plugin, SPPlatformAccessRef *resourceAccess)
	Retrieves the platform-specific resource access information of a plug-in accessor.
SPAPI SPErr(*	SetPluginResourceAccess )(SPPluginRef plugin, SPPlatformAccessRef resourceAccess)
	Sets the the platform-specific resource access information for a plug-in.
SPAPI SPErr(*	CallPlugin )(SPAccessRef access, const char caller, const char selector, void message, SPErr result)
	Sends a message to a plug-in, using an accessor object.
SPAPI SPErr(*	GetCurrentPlugin )(SPPluginRef *plugin)
	Retrieves the current plug-in, whose access information is the current resource context.
SPAPI SPErr(*	SetCurrentPlugin )(SPPluginRef plugin)
	Makes a plug-in and its resource context current.

Detailed Description

This suite is used to load and unload plug-ins.

The functions allow you to send messages directly to another plug-in. For example:

        SPErr SendMessage( SPPluginRef plugin, const char *caller, const char *selector, void *message, SPErr *error ) {

                SPErr result;
                SPAccessRef access;

                access = sAccess->AcquirePlugin( plugin, error );
                fail( error );

                result = sAccess->CallPlugin( access, caller, selector, message, error );
                fail( error );

                sAccess->ReleasePlugin( access, error );
                fail( error );

                return result;
        }

Standard PICA plug-ins rarely call one another directly. Usually program control flows from plug-in to plug-in through higher-level suites. Plug-in adapters, which provide protocol conversion to non-PICA plug-ins, can add their own access suites to provide access to their foreign plug-ins.

See also:: SPInterfaceSuite

Acquire this suite using SPBasicSuite::AcquireSuite() with the constants kSPAccessSuite and kSPAccessSuiteVersion.

Member Data Documentation

SPAPI SPErr(* SPAccessSuite::AcquirePlugin)(SPPluginRef plugin, SPAccessRef *access)

Loads a plug-in if necessary, and prepares it to be called.

Creates an accessor object if necessary, or increments the reference count of the existing accessor. Use ReleasePlugin() to decrement the count when you not longer need the accessor.

A plug-in can acquire itself in order to remain in memory, even if not referenced by any other plug-in.

Parameters:

	plugin	The plug-in object.
	access	[out] A buffer in which to return the new access object.

SPAPI SPErr(* SPAccessSuite::CallPlugin)(SPAccessRef access, const char *caller, const char *selector, void *message, SPErr *result)

Sends a message to a plug-in, using an accessor object.

Parameters:

	access	The access object.
	caller	The caller.
	slector	The selector.
	message	The message, as required for the selector.
	result	[out] A buffer in which to return the result of the call, returned by the called plug-in.

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

Retrieves the current reference count of an accessor object.

Parameters:

	access	The access object.
	count	[out] A buffer in which to return the count.

SPAPI SPErr(* SPAccessSuite::GetAccessEntry)(SPAccessRef access, SPEntry *entry)

Retrieves the entry point of a plug-in accessor.

This is the point to which CallPlugin() jumps. Before accessing the entry point directly, use SetCurrentPlugin() to make the plug-in current.

Parameters:

	access	The access object.
	entry	[out] A buffer in which to return the entry point structure.

SPAPI SPErr(* SPAccessSuite::GetAccessInfo)(SPAccessRef access, SPPlatformAccessInfo *info)

Retrieves the platform-specific resource access information of a plug-in accessor.

This is for the resource-chain in Mac OS, or the plug-in library in Windows.

Parameters:

	access	The access object.
	info	[out] A buffer in which to return the information structure.

SPAPI SPErr(* SPAccessSuite::GetAccessPlugin)(SPAccessRef access, SPPluginRef *plugin)

Retrieves the plug-in for an accessor.

Parameters:

	access	The access object.
	plugin	[out] A buffer in which to return the plug-in object, regardless of whether the plug-in is actually loaded into memory.

SPAPI SPErr(* SPAccessSuite::GetCurrentPlugin)(SPPluginRef *plugin)

Retrieves the current plug-in, whose access information is the current resource context.

This is typically the last plug-in to receive a call, but can be set by a plug-in adapter, or by SetCurrentPlugin().

Parameters:

plugin

[out] A buffer in which to return the plug-in object,

SPAPI SPErr(* SPAccessSuite::GetPluginAccess)(SPPluginRef plugin, SPAccessRef *access)

Retrieves the accessor object for a plug-in.

You can use this to get the accessor for your own plug-in, in order to access the resource chain or library information.

Used by plug-ins that export suites to manually establish a resource context within any of the suite procedures, so that they can access resources. Not needed when a plug-in is called through its entry point. SPAccessSuite::CallPlugin() sets up the resource context for you.

Parameters:

	plugin	The plug-in object.
	access	[out] A buffer in which to return the access object, or `NULL` if the plug-in is not loaded.

SPAPI SPErr(* SPAccessSuite::GetPluginResourceAccess)(SPPluginRef plugin, SPPlatformAccessRef *resourceAccess)

Retrieves the platform-specific resource access information of a plug-in accessor.

This is for the resource-chain in Mac OS, or the plug-in library in Windows.

Parameters:

	access	The access object.
	info	[out] A buffer in which to return the information structure. This differs from `SPAccessSuite::GetAccessInfo()`, which takes an `SPAccessRef` and returns the `SPPlatformAccessInfo`.

SPAPI SPErr(* SPAccessSuite::ReleasePlugin)(SPAccessRef access)

Decrements the reference count of an accessor object.

When the reference count reaches 0, frees the accessor object and allows the associated plug-in to be unloaded.

Parameters:

access

The access object.

SPAPI SPErr(* SPAccessSuite::SetCurrentPlugin)(SPPluginRef plugin)

Makes a plug-in and its resource context current.

An adapter can use this to set the resource context before making a call to a plug-in. Before making this call, you should save the reference for the current plug-in, and restore it when this plug-in no longer needs to be current.

Parameters:

plugin

The plug-in object,

SPAPI SPErr(* SPAccessSuite::SetPluginResourceAccess)(SPPluginRef plugin, SPPlatformAccessRef resourceAccess)

Sets the the platform-specific resource access information for a plug-in.

Parameters:

	plugin	The plug-in object.
	resourceAccess	The new resource-access information.

The documentation for this struct was generated from the following file:

SPAccess.h

SPAccessSuite Struct Reference [API Suite List]

Public Attributes

Detailed Description

Member Data Documentation

SPAccessSuite Struct Reference
[API Suite List]