SPAdaptersSuite Struct Reference
[API Suite List]

An adapter is an interface between the PICA plug-in manager and an individual plug-in. More...

#include <SPAdapts.h>

Public Attributes
SPAPI SPErr(*	AllocateAdapterList )(struct SPStringPool stringPool, SPAdapterListRef adapterList)
	Allocates a new list of adapters.
SPAPI SPErr(*	FreeAdapterList )(SPAdapterListRef adapterList)
	Frees a list of adapters allocated with `AllocateAdapterList()`, and also frees any entries in the list.
SPAPI SPErr(*	AddAdapter )(SPAdapterListRef adapterList, struct SPPlugin host, const char name, ai::int32 version, SPAdapterRef *adapter)
	Creates a new adapter object and adds it to an adapter list.
SPAPI SPErr(*	SPFindAdapter )(SPAdapterListRef adapterList, const char name, SPAdapterRef adapter)
	Retrieves an adapter by name.
SPAPI SPErr(*	NewAdapterListIterator )(SPAdapterListRef adapterList, SPAdapterListIteratorRef *iter)
	Creates an iterator object with which to traverse an adapter list.
SPAPI SPErr(*	NextAdapter )(SPAdapterListIteratorRef iter, SPAdapterRef *adapter)
	Retrieves the current adapter and advances an adapter-list iterator to the next adapter in the list.
SPAPI SPErr(*	DeleteAdapterListIterator )(SPAdapterListIteratorRef iter)
	Frees an adapter-list iterator that is no longer needed.
SPAPI SPErr(*	GetAdapterHost )(SPAdapterRef adapter, struct SPPlugin **plugin)
	Retrieves the plug-in that an adapter manages.
SPAPI SPErr(*	GetAdapterName )(SPAdapterRef adapter, const char **name)
	Retrieves the unique, identifying name of an adapter.
SPAPI SPErr(*	GetAdapterVersion )(SPAdapterRef adapter, ai::int32 *version)
	Retrieves the version of an adapter.

Detailed Description

An adapter is an interface between the PICA plug-in manager and an individual plug-in.

PICA and application plug-ins are hosted by internal PICA adapters. Plug-ins can add other adapters to PICA's adapter list, allowing non-PICA plug-ins to run under the PICA API.

Acquire this suite using SPBasicSuite::AcquireSuite() with the constants kSPAdaptersSuite and kSPAdaptersSuiteVersion.

An adapter searches the PICA file list (kSPRuntimeFileList) for plug-ins types that it supports, and adds them to the plug-in list (kSPRuntimePluginList). When notified by PICA to do so, the adapter is responsible for loading and calling the plug-ins it adds, and must do any conversion of messages, data structures or other API elements. An adapter can be used to update

There are always at least two adapters, the internal adapters for PICA and for the application, in the global adapter list (kSPRuntimeAdapterList). The internal adapters translate any legacy function calls into those currently supported by PICA and the application.

You can provide an adapter for backward compatibility with older versions of your own plug-ins, or to interpret your own file types. To make an adapter available for your plug-in, add it in response to the kSPAdaptersRegisterPluginsSelector when your plug-in is loaded.

You can also use this suite to create and maintain your own adapter list, in addition to the global list.

Use the adapter to load and call the adapted plug-in. For example, to verify that a message could be sent to a plug-in:

SPErr error;
SPPluginRef pluginToCall;
SPAdapterRef pluginsAdapter;
char *adapterName;
long adapterVersion;

error = sSPPlugins->GetPluginAdapter( pluginToCall, &pluginsAdapter );
error = sSPAdapters->GetAdapterName( pluginsAdapter, &adapterName );
if ( strcmp( adapterName, kSPSweetPea2Adapter ) == 0 ) {
        // it is a PICA plug-in, call it as such with sSPInterface.
        } else if ( strcmp( adapterName, "MYAPP Legacy Plug-in Adapter" ) == 0 ) {
                // it is an adapted plug-in, call it with the adapter�s
                // interface suite
                error = sSPAdapters->GetAdapterVersion( pluginsAdapter, &adapterVersion );
                if ( adapterVersion == 1 ) {
                        // use one hypothetical interface suite
                        } else if ( adapterVersion == 2) {
                        // use another hypothetical interface suite
                }
        }

Member Data Documentation

SPAPI SPErr(* SPAdaptersSuite::AddAdapter)(SPAdapterListRef adapterList, struct SPPlugin *host, const char *name, ai::int32 version, SPAdapterRef *adapter)

Creates a new adapter object and adds it to an adapter list.

Do this in response to the kSPAdaptersRegisterPluginsSelector message.

Parameters:

	adapterList	The adapter list object, or `NULL` to use the global list.
	host	This plug-in object, for which the adapter is responsible.
	name	The unique, identifying name of the adapter.
	version	The version number of the adapter. Only the latest version of any adapter is used to start up plug-ins.
	adapter	[out] A buffer in which to return the new adapter object, or `NULL` if you add only one adapter. If you add more than one adapter, compare this to `SPAdaptersMessage::adapter` to determine which handler to use.

See also:: AllocateAdapterList()

SPAPI SPErr(* SPAdaptersSuite::AllocateAdapterList)(struct SPStringPool *stringPool, SPAdapterListRef *adapterList)

Allocates a new list of adapters.

You can keep your own list, or obtain the global list with SPRuntimeSuite::GetRuntimeAdapterList().

Parameters:

	stringPool	The string pool in which to keep adapter names.
	adapterList	[out] A buffer in which to return the new list object.

SPAPI SPErr(* SPAdaptersSuite::DeleteAdapterListIterator)(SPAdapterListIteratorRef iter)

Frees an adapter-list iterator that is no longer needed.

Parameters:

iter

The adapter-list iterator object.

See also:: NewAdapterListIterator(),

SPAPI SPErr(* SPAdaptersSuite::FreeAdapterList)(SPAdapterListRef adapterList)

Frees a list of adapters allocated with AllocateAdapterList(), and also frees any entries in the list.

Do not free the global list (kSPRuntimeAdapterList).

Parameters:

adapterList

The adapter list object.

SPAPI SPErr(* SPAdaptersSuite::GetAdapterHost)(SPAdapterRef adapter, struct SPPlugin **plugin)

Retrieves the plug-in that an adapter manages.

Parameters:

	adapter	The adapter object.
	plug-in	[out] A buffer in which to return the plug-in object.

SPAPI SPErr(* SPAdaptersSuite::GetAdapterName)(SPAdapterRef adapter, const char **name)

Retrieves the unique, identifying name of an adapter.

Parameters:

	adapter	The adapter object.
	name	[out] A buffer in which to return the name string.

SPAPI SPErr(* SPAdaptersSuite::GetAdapterVersion)(SPAdapterRef adapter, ai::int32 *version)

Retrieves the version of an adapter.

Parameters:

	adapter	The adapter object.
	version	[out] A buffer in which to return the version number.

SPAPI SPErr(* SPAdaptersSuite::NewAdapterListIterator)(SPAdapterListRef adapterList, SPAdapterListIteratorRef *iter)

Creates an iterator object with which to traverse an adapter list.

The iterator is initially set to the first adapter in the list.

Parameters:

	adapterList	The adapter list object, or `NULL` to use the global list.
	iter	[out] A buffer in which to return the new iterator object.

See also:: NextAdapter(), DeleteAdapterListIterator()

SPAPI SPErr(* SPAdaptersSuite::NextAdapter)(SPAdapterListIteratorRef iter, SPAdapterRef *adapter)

Retrieves the current adapter and advances an adapter-list iterator to the next adapter in the list.

Parameters:

	iter	The adapter-list iterator object.
	adapter	[out] A buffer in which to return the current adapter object, `NULL` if the end of the list has been reached.

See also:: NewAdapterListIterator(),

SPAPI SPErr(* SPAdaptersSuite::SPFindAdapter)(SPAdapterListRef adapterList, const char *name, SPAdapterRef *adapter)

Retrieves an adapter by name.

Parameters:

	adapterList	The adapter list object, or `NULL` to use the global list.
	name	The unique, identifying name of the adapter.
	adapter	[out] A buffer in which to return the adapter object.

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

SPAdapts.h

SPAdaptersSuite Struct Reference [API Suite List]

Public Attributes

Detailed Description

Member Data Documentation

SPAdaptersSuite Struct Reference
[API Suite List]