SPPropertiesSuite Struct Reference
[API Suite List]

Use these functions to create, access, and manage plug-in property lists associated with a specific plug-in. More...

#include <SPProps.h>

Public Attributes
SPAPI SPErr(*	AllocatePropertyList )(SPPropertyListRef *propertyList)
	Creates a new plug-in property list.
SPAPI SPErr(*	FreePropertyList )(SPPropertyListRef propertyList)
	Frees a list of plug-in properties allocated with `AllocatePropertyList()`, and also frees any entries in the list.
SPAPI SPErr(*	AddProperties )(SPPropertyListRef propertyList, PIPropertyList *pList, ai::int32 refCon, ai::int32 cacheable)
	Adds a set of properties to a plug-in properties list.
SPAPI SPErr(*	AddProperty )(SPPropertyListRef propertyList, PIType vendorID, PIType propertyKey, ai::int32 propertyID, PIProperty p, ai::int32 refCon, ai::int32 cacheable, SPPropertyRef property)
	Creates a new individual property and adds it to a plug-in properties list.
SPAPI SPErr(*	FindProperty )(SPPropertyListRef propertyList, PIType vendorID, PIType propertyKey, ai::int32 propertyID, SPPropertyRef *property)
	Retrieves a property from a plug-in properties list, or from any list in its chain.
SPAPI SPErr(*	NewPropertyListIterator )(SPPropertyListRef propertyList, SPPropertyListIteratorRef *iter)
	Creates an iterator object with which to traverse a plug-in properties list.
SPAPI SPErr(*	NextProperty )(SPPropertyListIteratorRef iter, SPPropertyRef *property)
	Retrieves the current property and advances a plug-in properties list iterator to the next property in the list.
SPAPI SPErr(*	DeletePropertyListIterator )(SPPropertyListIteratorRef iter)
	Frees a plug-in properties list iterator that is no longer needed.
SPAPI SPErr(*	GetPropertyPIProperty )(SPPropertyRef property, PIProperty **p)
	Retrieves the low-level property structure of a property object.
SPAPI SPErr(*	GetPropertyRefCon )(SPPropertyRef property, ai::int32 *refCon)
	Retrieves the current reference count of a property.
SPAPI SPErr(*	GetPropertyCacheable )(SPPropertyRef property, ai::int32 *cacheable)
	Reports whether a property is cacheable.
SPAPI SPErr(*	GetPropertyAllocatedByPlugin )(SPPropertyRef property, ai::int32 *allocatedByPlugin)
	Reports whether a property was allocated by the plug-in that contains it.
SPAPI SPBoolean(*	SPHasMultiplePropertyLists )(SPPropertyListRef propertyList)
	Reports whether a plug-in properties list is one of a chain of properties lists for its plug-in.
SPAPI SPErr(*	GetNextPropertyList )(SPPropertyListRef propertyList, SPPropertyListRef *nextPropertyList)
	Retrieves the next plug-in properties list in a properties-list chain.
SPAPI SPErr(*	FindPropertyLocal )(SPPropertyListRef propertyList, PIType vendorID, PIType propertyKey, ai::int32 propertyID, SPPropertyRef *property)
	Retrieves a property from a plug-in properties list, but does not search in other lists in the chain.

Detailed Description

Use these functions to create, access, and manage plug-in property lists associated with a specific plug-in.

Plug-in properties provide the application with resource information for the plug-in, such as the types and locations of code files, and the plug-in version.

A plug-in can be associated with multiple properties lists.

Acquire this suite using SPBasicSuite::AcquireSuite() with the constants kSPPropertiesSuite and kSPPropertiesSuiteVersion.

Member Data Documentation

SPAPI SPErr(* SPPropertiesSuite::AddProperties)(SPPropertyListRef propertyList, PIPropertyList *pList, ai::int32 refCon, ai::int32 cacheable)

Adds a set of properties to a plug-in properties list.

This set is typically read from a resource file.Creates an SPPropertyRef for each property, but does not return these objects.

Parameters:

	propertyList	The plug-in properties list object.
	pList	A pointer to the low-level structure for the set of properties to add.
	refCon	The initial reference count for properties in the set.
	cacheable	True (non-zero) if these properties do not change between sessions and can be cached by the application in the start-up preferences file, false (0) otherwise. Typically true.

See also:: AddProperty()

SPAPI SPErr(* SPPropertiesSuite::AddProperty)(SPPropertyListRef propertyList, PIType vendorID, PIType propertyKey, ai::int32 propertyID, PIProperty *p, ai::int32 refCon, ai::int32 cacheable, SPPropertyRef *property)

Creates a new individual property and adds it to a plug-in properties list.

Typically called to install a property returned from an kSPPropertiesAcquireSelector message.

Parameters:

	propertyList	The plug-in properties list object.
	vendorID	The vendor identifier for the new property.
	propertyKey	The type key code for the new property.
	propertyID	The unique identifier for the individual property (normally 0).
	p	A pointer to the property value structure.
	refCon	The initial reference count for property.
	cacheable	True (non-zero) if this property does not change between sessions and can be cached by the application in the start-up preferences file, false (0) otherwise. Typically true.
	property	[out] A buffer in which to return the new property object.

See also:: AllocatePropertyList(), AddProperties()

SPAPI SPErr(* SPPropertiesSuite::AllocatePropertyList)(SPPropertyListRef *propertyList)

Creates a new plug-in property list.

Parameters:

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

SPAPI SPErr(* SPPropertiesSuite::DeletePropertyListIterator)(SPPropertyListIteratorRef iter)

Frees a plug-in properties list iterator that is no longer needed.

Parameters:

iter

The plug-in properties list iterator object.

See also:: NewPropertyListIterator(),

SPAPI SPErr(* SPPropertiesSuite::FindProperty)(SPPropertyListRef propertyList, PIType vendorID, PIType propertyKey, ai::int32 propertyID, SPPropertyRef *property)

Retrieves a property from a plug-in properties list, or from any list in its chain.

Parameters:

	propertyList	The plug-in properties list object.
	vendorID	The vendor identifier for the new property.
	propertyKey	The type key code for the new property.
	propertyID	The unique identifier for the individual property (normally 0).
	property	[out] A buffer in which to return the property object, or `NULL` if a matching property is not found.
	\c	FindPropertyLocal()

SPAPI SPErr(* SPPropertiesSuite::FindPropertyLocal)(SPPropertyListRef propertyList, PIType vendorID, PIType propertyKey, ai::int32 propertyID, SPPropertyRef *property)

Retrieves a property from a plug-in properties list, but does not search in other lists in the chain.

Parameters:

	propertyList	The plug-in properties list object.
	vendorID	The vendor identifier for the new property.
	propertyKey	The type key code for the new property.
	propertyID	The unique identifier for the individual property (normally 0).
	property	[out] A buffer in which to return the property object, or `NULL` if a matching property is not found.

See also:: FindProperty()

SPAPI SPErr(* SPPropertiesSuite::FreePropertyList)(SPPropertyListRef propertyList)

Frees a list of plug-in properties allocated with AllocatePropertyList(), and also frees any entries in the list.

If the list is one of a chain, frees the entire chain.

Parameters:

propertyList

The plug-in properties list object.

See also:: SPHasMultiplePropertyLists()

SPAPI SPErr(* SPPropertiesSuite::GetNextPropertyList)(SPPropertyListRef propertyList, SPPropertyListRef *nextPropertyList)

Retrieves the next plug-in properties list in a properties-list chain.

Parameters:

	propertyList	The current plug-in properties list object.
	nextPropertyList	[out] A buffer in which to return the next properties list object, or `NULL` if the end of the chain has been reached.

SPAPI SPErr(* SPPropertiesSuite::GetPropertyAllocatedByPlugin)(SPPropertyRef property, ai::int32 *allocatedByPlugin)

Reports whether a property was allocated by the plug-in that contains it.

Parameters:

	property	The property object.
	allocatedByPlugin	[out] A buffer in which to return true (non-zero) if this property was created after being acquired from a `kSPPropertiesAcquireSelector` message, false (0) if the property was read from a resource file.

See also:: AddProperty(), AddProperties()

SPAPI SPErr(* SPPropertiesSuite::GetPropertyCacheable)(SPPropertyRef property, ai::int32 *cacheable)

Reports whether a property is cacheable.

Parameters:

	property	The property object.
	cacheable	[out] A buffer in which to return true (non-zero) if this property does not change between sessions and can be cached by the application in the start-up preferences file, false (0) otherwise.

SPAPI SPErr(* SPPropertiesSuite::GetPropertyPIProperty)(SPPropertyRef property, PIProperty **p)

Retrieves the low-level property structure of a property object.

Parameters:

	property	The property object.
	p	[out] A buffer in which to return a pointer to the property structure.

SPAPI SPErr(* SPPropertiesSuite::GetPropertyRefCon)(SPPropertyRef property, ai::int32 *refCon)

Retrieves the current reference count of a property.

Parameters:

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

SPAPI SPErr(* SPPropertiesSuite::NewPropertyListIterator)(SPPropertyListRef propertyList, SPPropertyListIteratorRef *iter)

Creates an iterator object with which to traverse a plug-in properties list.

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

Parameters:

	propertyList	The plug-in properties list object.
	iter	[out] A buffer in which to return the new iterator object.

See also:: NextProperty(), DeletePropertyListIterator()

SPAPI SPErr(* SPPropertiesSuite::NextProperty)(SPPropertyListIteratorRef iter, SPPropertyRef *property)

Retrieves the current property and advances a plug-in properties list iterator to the next property in the list.

Parameters:

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

See also:: NewPropertyListIterator(),

SPAPI SPBoolean(* SPPropertiesSuite::SPHasMultiplePropertyLists)(SPPropertyListRef propertyList)

Reports whether a plug-in properties list is one of a chain of properties lists for its plug-in.

(Note that this function returns a boolean value, not an error code.)

Parameters:

propertyList

The plug-in properties list object.

Returns:: True (non-zero) if the list is one of a chain, false (0) otherwise.

See also:: GetNextPropertyList()

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

SPProps.h

SPPropertiesSuite Struct Reference [API Suite List]

Public Attributes

Detailed Description

Member Data Documentation

SPPropertiesSuite Struct Reference
[API Suite List]