AIUIDREFSuite Struct Reference
[API Suite List]

This suite allows you to access and manage references to unique identifiers. More...

#include <AIUID.h>

List of all members.

Public Attributes
AIAPI ai::int32(*	AddRef )(void *uidref)
	Increments the reference count for a UID reference.
AIAPI ai::int32(*	Release )(void *uidref)
	Decrements the reference count for a UID reference, and frees the memory when the reference count is 0.
AIAPI AIBoolean(*	IsInUse )(AIUIDREFRef uidref)
	Reports whether a UID reference is currently stored within some container.
AIAPI void(*	GetPool )(AIUIDREFRef uidref, AINamePoolRef *pool)
	Retrieves the UID name pool to which a UID reference's name belongs.
AIAPI AIErr(*	GetName )(AIUIDREFRef uidref, ai::UnicodeString &name)
	Retrieves the name of a UID reference as a Unicode string.
AIAPI AIEntryRef(*	GetContainer )(AIUIDREFRef uidref)
	Retrieves the dictionary or array that contains a UID reference.
AIAPI void(*	GetUID )(AIUIDREFRef uidref, AIUIDRef *uid)
	Retrieves the unique identifier referred to by a UID reference.

---

Detailed Description

This suite allows you to access and manage references to unique identifiers.

The AIEntrySuite provides methods to convert between AIEntryRef and AIUIDRef.

Use a UID to tag an object with a unique identifier, then use a UID reference to make a reference to that object. For example, if your plug-in creates art objects and you want to attach a unique identifier to an object, first create a UID and put it in the art object�s dictionary. You can then store a reference to the object in the document dictionary using an AIUIDRef.

See also:

AIUIDPoolSuite, AIUIDSuite, AIUIDUtilsSuite

• Acquire this suite using SPBasicSuite::AcquireSuite() with the constants kAIUIDREFSuite and kAIUIDREFVersion.

---

Member Data Documentation

AIAPI ai::int32(* AIUIDREFSuite::AddRef)(void *uidref)

Increments the reference count for a UID reference.

When you create an AIUIDRef, the initial count is 1. Use Release() to decrement the count. (Note that this function returns a numeric value, not an error code.)

Parameters:

uidref

The UID reference object.

Returns:

The current reference count.

AIAPI AIEntryRef(* AIUIDREFSuite::GetContainer)(AIUIDREFRef uidref)

Retrieves the dictionary or array that contains a UID reference.

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

Parameters:

uidref

The UID reference object.

Returns:

The entry object, or a NULL reference if the UID reference is not stored in a container.

See also:

AIEntrySuite

AIAPI AIErr(* AIUIDREFSuite::GetName)(AIUIDREFRef uidref, ai::UnicodeString &name)

Retrieves the name of a UID reference as a Unicode string.

Parameters:

	uidref	The UID reference object.
	name	[out] A buffer in which to return the name.

AIAPI void(* AIUIDREFSuite::GetPool)(AIUIDREFRef uidref, AINamePoolRef *pool)

Retrieves the UID name pool to which a UID reference's name belongs.

(Note that this function does not return an error code.)

Parameters:

	uidref	The UID reference object.
	pool	[out] A buffer in which to return the UID name pool, or NULL if the UID reference is not valid.

AIAPI void(* AIUIDREFSuite::GetUID)(AIUIDREFRef uidref, AIUIDRef *uid)

Retrieves the unique identifier referred to by a UID reference.

(Note that this function does not return an error code.)

Parameters:

	uidref	The UID reference object.
	uid	[out] A buffer in which to return the UID object, or NULL if there is none.

AIAPI AIBoolean(* AIUIDREFSuite::IsInUse)(AIUIDREFRef uidref)

Reports whether a UID reference is currently stored within some container.

A UID cannot occur in more than one container, or more than once in a container. (Note that this function returns a boolean value, not an error code.)

Parameters:

uidref

The UID reference object.

Returns:

True if the UID reference is contained in a dictionary or array.

AIAPI ai::int32(* AIUIDREFSuite::Release)(void *uidref)

Decrements the reference count for a UID reference, and frees the memory when the reference count is 0.

When you create an AIUIDRef, the initial count is 1. Use AddRef() to increment the count. (Note that this function returns a numeric value, not an error code.)

Parameters:

uidref

The UID reference object.

Returns:

The current reference count.

---

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

• AIUID.h