SPBasicSuite Struct Reference
[API Suite List]

This suite provides basic memory management for PICA (the Adobe plug-in manager) and defines the basic functions for acquiring and releasing other suites. More...

#include <SPBasic.h>

List of all members.

Public Attributes
SPAPI SPErr(*	AcquireSuite )(const char *name, ai::int32 version, const void **suite)
	Acquires a function suite.
SPAPI SPErr(*	ReleaseSuite )(const char *name, ai::int32 version)
	Decrements the reference count of a suite and unloads it when the reference count reaches 0.
SPAPI SPBoolean(*	IsEqual )(const char *token1, const char *token2)
	Compares two strings for equality.
SPAPI SPErr(*	AllocateBlock )(size_t size, void **block)
	Allocates a block of memory.
SPAPI SPErr(*	FreeBlock )(void *block)
	Frees a block of memory allocated with AllocateBlock().
SPAPI SPErr(*	ReallocateBlock )(void *block, size_t newSize, void **newblock)
	Reallocates a block previously allocated with AllocateBlock().
SPAPI SPErr(*	Undefined )(void)
	A function pointer for unloaded suites.

---

Detailed Description

This suite provides basic memory management for PICA (the Adobe plug-in manager) and defines the basic functions for acquiring and releasing other suites.

A suite consists of a list of function pointers. The application, or a plug-in that loads a suite, provides valid pointers when the suite is acquired. When a suite is not available, the pointers are set to the address of the Undefined() function.

Do not attempt to acquire a suite (other than the SPBlocksSuite) in response to a PICA access (kSPAccessCaller) or property (kSPPropertiesCaller) message. Most suites are unavailable during these load and unload operations.

You can acquire all the suites you will need when your plug-in is first loaded, as long as you release them before your plug-in is unloaded. At shutdown, however, it is most efficient to acquire only those suites explicitly needed to shut down; for example, to free memory and save preferences.

The SPBasicSuite itself is a part of the message data passed to your plug-in with any call. To access it from the message data structure:

        SPBasicSuite sBasic = message->d.basic;
        sBasic->function( )

---

Member Data Documentation

SPAPI SPErr(* SPBasicSuite::AcquireSuite)(const char *name, ai::int32 version, const void **suite)

Acquires a function suite.

Loads the suite if necessary, and increments its reference count. For example:

SPErr error;
SPBasicSuite *sBasic = message->d.basic;
AIRandomSuite *sRandom;
sBasic->AcquireSuite( kAIRandomSuite, kAIRandomVersion, &sRandom );

Parameters:

	name	The suite name.
	version	The suite version number.
	suite	[out] A buffer in which to return the suite pointer.

See also:

SPSuitesSuite::AcquireSuite()

Referenced by ASUserInteractionChecker::ASUserInteractionChecker().

SPAPI SPErr(* SPBasicSuite::AllocateBlock)(size_t size, void **block)

Allocates a block of memory.

Parameters:

	size	The number of bytes.
	block	[out] A buffer in which to return the block pointer.

See also:

SPBlocksSuite::AllocateBlock()

Referenced by operator new(), and operator new[]().

SPAPI SPErr(* SPBasicSuite::FreeBlock)(void *block)

Frees a block of memory allocated with AllocateBlock().

Parameters:

block

The block pointer.

See also:

SPBlocksSuite::FreeBlock()

Referenced by operator delete(), and operator delete[]().

SPAPI SPBoolean(* SPBasicSuite::IsEqual)(const char *token1, const char *token2)

Compares two strings for equality.

Parameters:

	token1	The first null-terminated string.
	token2	The second null-terminated string.

Returns:

True if the strings are the same, false otherwise.

SPAPI SPErr(* SPBasicSuite::ReallocateBlock)(void *block, size_t newSize, void **newblock)

Reallocates a block previously allocated with AllocateBlock().

Increases the size without changing the location, if possible.

Parameters:

	block	The block pointer.
	newSize	The new number of bytes.
	newblock	[out] A buffer in which to return the new block pointer.

See also:

SPBlocksSuite::ReallocateBlock()

SPAPI SPErr(* SPBasicSuite::ReleaseSuite)(const char *name, ai::int32 version)

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

Parameters:

	name	The suite name.
	version	The suite version number.

Referenced by ASUserInteractionChecker::~ASUserInteractionChecker().

SPAPI SPErr(* SPBasicSuite::Undefined)(void)

A function pointer for unloaded suites.

This is a protective measure against other plug-ins that may mistakenly use the suite after they have released it.

A plug-in that exports a suite should unload the suite's procedure pointers when it is unloaded, and restore them when the plug-in is reloaded.

• On unload, replace the suite's procedure pointers with the address of this function.
• On reload, restore the suite's procedure pointers with the updated addresses of their functions.

For example:

                SPErr UnloadSuite( MySuite *mySuite, SPAccessMessage *message ) {
                        mySuite->functionA = (void *) message->d.basic->Undefined;
                        mySuite->functionB = (void *) message->d.basic->Undefined;
                }

                SPErr ReloadSuite( MySuite *mySuite, SPAccessMessage *message ) {
                        mySuite->functionA = functionA;
                        mySuite->functionB = functionB;
                }

---

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

• SPBasic.h