MOA Developer's Guide
MOA Interfaces | MOA Methods | MOA Types and Misc API

IMoaDict

Interface ID: IID_IMoaDict
Pointer type: PIMoaDict
Inheritance: IMoaUnknown
Header file: moastdif.h

Description

This standard MOA callback interface is provided by the application for use in registering an Xtra. The description of the IMoaCache interface (earlier in this section) provides a detailed discussion of the Xtra registry.

The Xtra cache is organized into hierarchies of dictionaries, all represented by instances of the IMoaDict interface. Within the cache, each file is represented by a PIMoaFileEntryDict, each Xtra in a file is represented by a PIMoaXtraEntryDict, and each class/interface combination in an Xtra is represented by a PIMoaRegistryEntryDict. All these types are synonyms for PIMoaDict.

Each entry in a dictionary consists of three parts: a key, a type, and a value. The key is used to locate a specific entry. Keys for certain entries may be specified by an application. If an Xtra adds its own data to the cache, it can specify the keys to associate with particular values. A number of value types can be stored in a dictionary. The IMoaDict interface defines a set of constants to specify these types; these are documented in IMoaDict constants.

Xtras register themselves and add other entries to their registry dictionary by implementing the IMoaRegister interface. They can initialize themselves from information in the registry dictionary by implementing the IMoaInitFromDict interface. The IMoaDict interface is used to get and set individual entries in a dictionary.

See also

IMoaDict constants, IMoaDict errors

Methods

Creating and initializing

SetSize()
MakeDict()

Accessing entries

Get()
Count()
GetNth()
GetInfo()
FindKey()

Modifying entries

Put()
Remove()

Count()

Syntax

Count(MoaUlong * pCount)

Parameters

pCount
Integer pointer for return value

Returns

Internal lookup key

Description

Returns how many (key, type, value) tuples are in a dictionary.


FindKey()

Syntax

FindKey(ConstPMoaChar key)

Parameters

key
Key for the entry

Returns

Internal lookup key

Description

The method FindKey() returns the "magic" key used internally by the cache for fast access to a dictionary entry. Calling this method and storing the return value can provide much faster dictionary access to frequently accessed values. NULL will be returned when out of memory.

Get()

Syntax

Get(MoaDictTypeID type, PMoaVoid pValueBuffer, MoaLong bufferSize, ConstPMoaChar key)

Parameters

type
MoaDictTypeID of the value

pValueBuffer
Pointer to buffer for the returned value

bufferSize
Size of buffer for returned value

key
Key for the entry

Returns

MoaError

Description

Returns a value from a dictionary given its key.

GetInfo()

Syntax

GetInfo(MoaDictTypeID * pType, MoaLong * pValueSize, ConstPMoaChar key)

Parameters

pType
Returns the type of the value

pValueSize
Returns the size of the value

key
Key for entry

Returns

MoaError

Description

Returns information on the entry for the specified key in a dictionary. Pass NULL for pType or pValueSize if you're not interested in the specific information.

GetNth()

Syntax

GetNth(MoaUlong index, MoaDictTypeID * pType, MoaLong * pValueSize, ConstPMoaChar * pKey)

Parameters

index
Entry number to access

pType
Returns the type of the value

pValueSize
Returns the size of the value

pKey
Returns the key of the value

Returns

MoaError

Description

Returns information about entry number index in a dictionary. Pass NULL for pType, pValueSize, or pKey if you're not interested in the specific information.

MakeDict()

Syntax

MakeDict(struct IMoaDict * * pNewDict, ConstPMoaChar key)

Parameters

pNewDict
Allocated pointer to IMoaDict

key
Key for the entry

Returns

MoaError

Description

Call this method to create a new instance of IMoaDict and place it in the dictionary represented by This under the specified key. Pass an allocated PIMoaDict as pNewDict to get a pointer to the new instance; otherwise, pass NULL. The newly created dictionary is "owned" by This; the caller need not call Release() on it.

Put()

Syntax

Put(MoaDictTypeID type, ConstPMoaVoid pValueBuffer, MoaLong bufferSize, ConstPMoaChar key)

Parameters

type
MoaDictTypeID of the value

pValueBuffer
Pointer to buffer for the value

bufferSize
Size of buffer for value

key
Key for the entry

Returns

MoaError

Description

Inserts the value pValueBuffer of the specified type, bufferSize, and key into the dictionary This.

Remove()

Syntax

Remove(ConstPMoaChar key)

Parameters

key
Key for the entry

Returns

MoaError

Description

Looks up the value associated with key and removes it from a dictionary. For reference counted types (interfaces), the count will simply be decremented.

SetSize()

Syntax

SetSize(MoaUlong numEntries)

Parameters

numEntries
Integer representing number of entries

Returns

MoaError

Description

Call this method to pre-allocate space in a dictionary. This makes adding to the dictionary more efficient if the size is more-or-less known before hand.

Copyright © 1995-2008 Adobe Macromedia Software LLC, Inc.