SPSuitesSuite Struct Reference
[API Suite List]

This suite allows you to create, manage, and access PICA function suites. More...

#include <SPSuites.h>

Public Attributes
SPAPI SPErr(*	AllocateSuiteList )(SPStringPoolRef stringPool, SPPluginListRef plugins, SPSuiteListRef *suiteList)
	Creates a new suite list.
SPAPI SPErr(*	FreeSuiteList )(SPSuiteListRef suiteList)
	Frees a list of suites allocated with `AllocateSuiteList()`, and also frees any entries in the list.
SPAPI SPErr(*	AddSuite )(SPSuiteListRef suiteList, SPPluginRef host, const char name, ai::int32 apiVersion, ai::int32 internalVersion, const void suiteProcs, SPSuiteRef *suite)
	Creates a new plug-in function suite and adds it to a suite list.
SPAPI SPErr(*	AcquireSuite )(SPSuiteListRef suiteList, const char name, ai::int32 apiVersion, ai::int32 internalVersion, const void *suiteProcs)
	Acquires a function suite from a suite list.
SPAPI SPErr(*	ReleaseSuite )(SPSuiteListRef suiteList, const char *name, ai::int32 apiVersion, ai::int32 internalVersion)
	Decrements the reference count of a suite in a suite list and unloads it when the reference count reaches 0.
SPAPI SPErr(*	FindSuite )(SPSuiteListRef suiteList, const char name, ai::int32 apiVersion, ai::int32 internalVersion, SPSuiteRef suite)
	Retrieves a suite from a suite list.
SPAPI SPErr(*	NewSuiteListIterator )(SPSuiteListRef suiteList, SPSuiteListIteratorRef *iter)
	Creates an iterator object with which to traverse a suite list.
SPAPI SPErr(*	NextSuite )(SPSuiteListIteratorRef iter, SPSuiteRef *suite)
	Retrieves the current suite and advances a suite-list iterator to the next suite in the list.
SPAPI SPErr(*	DeleteSuiteListIterator )(SPSuiteListIteratorRef iter)
	Frees a suite-list iterator that is no longer needed.
SPAPI SPErr(*	GetSuiteHost )(SPSuiteRef suite, SPPluginRef *plugin)
	Retrieves the plug-in that provides a suite.
SPAPI SPErr(*	GetSuiteName )(SPSuiteRef suite, const char **name)
	Retrieves the unique name of a suite.
SPAPI SPErr(*	GetSuiteAPIVersion )(SPSuiteRef suite, ai::int32 *version)
	Retrieves the public version number of a suite.
SPAPI SPErr(*	GetSuiteInternalVersion )(SPSuiteRef suite, ai::int32 *version)
	Retrieves the internal version number of a suite.
SPAPI SPErr(*	GetSuiteProcs )(SPSuiteRef suite, const void **suiteProcs)
	Retrieves the function pointer array of a suite.
SPAPI SPErr(*	GetSuiteAcquireCount )(SPSuiteRef suite, ai::int32 *count)
	Retrieves the current reference count of a suite.

Detailed Description

This suite allows you to create, manage, and access PICA function suites.

A suite associates a name and version number with a pointer to an array of function pointers. The functions generally haves some common purpose, such as accessing a data type, and are used by plug-ins to interact with PICA, with the application, and with each other.

In order to use a function in a suite, you must first acquire it. This suite provides the low-level function AcquireSuite(), but a plug-in more typically uses the SPBasicSuite, which is provided with every message to a plug-in.

PICA creates a global suite list at application startup, which contains references to every suite added by PICA, the application, or other plug-ins. You can use this suite to create and manage additional suite lists.

Acquire this suite using SPBasicSuite::AcquireSuite() with the constants kSPSuitesSuite and kSPSuitesSuiteVersion.

Member Data Documentation

SPAPI SPErr(* SPSuitesSuite::AcquireSuite)(SPSuiteListRef suiteList, const char *name, ai::int32 apiVersion, ai::int32 internalVersion, const void **suiteProcs)

Acquires a function suite from a suite list.

Loads the suite if necessary, and increments its reference count. This function differs from SPBasicSuite::AcquireSuite() in that you can specify a suite list and internal version number.

Parameters:

	suiteList	The suite list object, or `NULL` to use the global list.
	name	The suite name.
	version	The public suite version number.
	internalVersion	The internal suite version number.
	suiteProcs	[out] A buffer in which to return a pointer to the suite function pointer array.

SPAPI SPErr(* SPSuitesSuite::AddSuite)(SPSuiteListRef suiteList, SPPluginRef host, const char *name, ai::int32 apiVersion, ai::int32 internalVersion, const void *suiteProcs, SPSuiteRef *suite)

Creates a new plug-in function suite and adds it to a suite list.

Identifying constants for the suite name and version must be made available in a public header file.

Parameters:

	suiteList	The suite list object, or `NULL` to use the global list.
	host	The plug-in object providing the suite.
	name	The unique name of the suite.
	apiVersion	The public version number of the suite.
	internalVersion	The internal version number of the suite.
	suiteProcs	A pointer to a structure containing the function pointers for the suite.
	suite	[out] A buffer in which to return the new suite object.

SPAPI SPErr(* SPSuitesSuite::AllocateSuiteList)(SPStringPoolRef stringPool, SPPluginListRef plugins, SPSuiteListRef *suiteList)

Creates a new suite list.

You can also access PICA's global suite list, using SPRuntimeSuite::GetRuntimeSuiteList().

Parameters:

	stringPool	The string pool in which to keep suite names.
	plugins	A set of plug-in objects.
	suiteList	[out] A buffer in which to return the new list object.

SPAPI SPErr(* SPSuitesSuite::DeleteSuiteListIterator)(SPSuiteListIteratorRef iter)

Frees a suite-list iterator that is no longer needed.

Parameters:

iter

The suite-list iterator object.

See also:: NewSuiteListIterator(),

SPAPI SPErr(* SPSuitesSuite::FindSuite)(SPSuiteListRef suiteList, const char *name, ai::int32 apiVersion, ai::int32 internalVersion, SPSuiteRef *suite)

Retrieves a suite from a suite list.

Parameters:

	suiteList	The suite list object, or `NULL` to use the global list.
	name	The suite name.
	version	The public suite version number.
	internalVersion	The internal suite version number.
	suiteProcs	[out] A buffer in which to return the suite object, or `NULL` if no matching suite is found in the list.

SPAPI SPErr(* SPSuitesSuite::FreeSuiteList)(SPSuiteListRef suiteList)

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

Do not free the global list (kSPRuntimeSuiteList).

Parameters:

suiteList

The suite list object.

SPAPI SPErr(* SPSuitesSuite::GetSuiteAcquireCount)(SPSuiteRef suite, ai::int32 *count)

Retrieves the current reference count of a suite.

Parameters:

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

SPAPI SPErr(* SPSuitesSuite::GetSuiteAPIVersion)(SPSuiteRef suite, ai::int32 *version)

Retrieves the public version number of a suite.

Parameters:

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

SPAPI SPErr(* SPSuitesSuite::GetSuiteHost)(SPSuiteRef suite, SPPluginRef *plugin)

Retrieves the plug-in that provides a suite.

Parameters:

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

SPAPI SPErr(* SPSuitesSuite::GetSuiteInternalVersion)(SPSuiteRef suite, ai::int32 *version)

Retrieves the internal version number of a suite.

Parameters:

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

SPAPI SPErr(* SPSuitesSuite::GetSuiteName)(SPSuiteRef suite, const char **name)

Retrieves the unique name of a suite.

Parameters:

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

SPAPI SPErr(* SPSuitesSuite::GetSuiteProcs)(SPSuiteRef suite, const void **suiteProcs)

Retrieves the function pointer array of a suite.

Parameters:

	suite	The suite object.
	suiteProcs	[out] A buffer in which to return a pointer to the function pointer array.

SPAPI SPErr(* SPSuitesSuite::NewSuiteListIterator)(SPSuiteListRef suiteList, SPSuiteListIteratorRef *iter)

Creates an iterator object with which to traverse a suite list.

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

Parameters:

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

See also:: NextSuite(), DeleteSuiteListIterator()

SPAPI SPErr(* SPSuitesSuite::NextSuite)(SPSuiteListIteratorRef iter, SPSuiteRef *suite)

Retrieves the current suite and advances a suite-list iterator to the next suite in the list.

Parameters:

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

See also:: NewSuiteListIterator(),

SPAPI SPErr(* SPSuitesSuite::ReleaseSuite)(SPSuiteListRef suiteList, const char *name, ai::int32 apiVersion, ai::int32 internalVersion)

Decrements the reference count of a suite in a suite list and unloads it when the reference count reaches 0.

Parameters:

	suiteList	The suite list object, or `NULL` to use the global list.
	name	The suite name.
	version	The public suite version number.
	internalVersion	The internal suite version number.

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

SPSuites.h

SPSuitesSuite Struct Reference [API Suite List]

Public Attributes

Detailed Description

Member Data Documentation

SPSuitesSuite Struct Reference
[API Suite List]