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

IMoaCache


Interface ID: IID_IMoaCache
Pointer type: PIMoaCache
Inheritance: IMoaUnknown
Header file: moastdif.h

Description


The IMoaCache interface is provided by all MOA applications for use in registering an Xtra. Xtras register themselves by implementing the Xtra interface IMoaRegister. They can initialize themselves from cached information by implementing the IMoaInitFromDict interface. To get access to the cache at other times, you call the MoaGetCache() method of the IMoaCallback interface. The IMoaDict interface is used to get and set individual entries in a cache.

An application's cache contains nested dictionaries of information about files contained in its Xtras folders, both the application-specific Xtras folder and the system-wide Xtras folder. The dictionaries in the cache form a nested hierarchy.

At the top level, the cache contains a dictionary for each file found in the Xtras folders. Cached files include all files found in the Xtras folders, both those that contain Xtras and those that don't. This enables an application to cache non-MOA extension files.

Within each file dictionary, there may be zero, one, or more Xtra dictionaries. A file dictionary will contain no Xtra dictionary if the file isn't an Xtras file. When a cached file contains Xtras, the file dictionary contains one Xtra dictionary for each Xtra.

Within each Xtra dictionary, the cache contains one registry dictionary per class/interface that an application registers. If a given Xtra contains three classes, each implementing an interface of interest to an application, its Xtra dictionary will contain three registry dictionaries.

The methods of IMoaCache provide mechanisms for registering classes and interfaces and for accessing the various dictionaries in a cache. The AddRegistryEntry() method is the main method used in an Xtra's IMoaRegister implementation to register its classes and interfaces. This method returns a pointer to a specific registry dictionary, which can be used to store other information about an Xtra class and its interface. Other methods can be used to access file dictionaries, Xtra dictionaries, and registry dictionaries. To manipulate the entries in a dictionary, you use methods of the IMoaDict interface.

Methods

Counting entries

EnumerateFileEntries()
EnumerateXtraEntries()
EnumerateRegistryEntries()
SetXtraEntryNoncacheable()

Modifying entries

AddRegistryEntry()

Creating an instance

GetInstanceFromRegistry()
CreateNewInstanceFromRegistry()

Accessing entries

EnumerateRegistryEntriesFromFile()
GetFileSpecFromFileDict()

AddRegistryEntry()

Syntax

AddRegistryEntry(PIMoaCacheThis,

PIMoaXtraEntryDictpXtraDict,
ConstPMoaClassIDpClassID,
ConstPMoaInterfaceIDpInterfaceID,
PIMoaRegistryEntryDict FAR *ppRegistryDict)

Parameters

This
Pointer to the IMoaCache interface

pXtraDict
PIMoaXtraEntryDictIMoaDict instance for the Xtra dictionary

pClassID
ConstPMoaClassIDCLSID of the class being registered

pInterfaceID
ConstPMoaInterfaceIDIID of the interface being registered

ppRegistryDict
PIMoaRegistryEntryDict FAR *IMoaDict instance for the registry dictionary

Returns

MoaError

Description


Call this method inside your Xtra's implementation of the Register() method to add a registry entry to the cache. Pass the instance of IMoaDict passed to you by Register()as the pXtraDict argument. The class and interface passed to this method are typically (but not necessarily) implemented within the same Xtra as the Register() method.

The argument for ppRegistryDict should be a pointer to an IMoaDict. The interface returned can be used to add custom information to the registry entry, such as any key/value combinations specified for a particular interface. If you don't need the registry dictionary, pass NULL.

Note: Do not call Release() on ppRegistryDict.


CreateNewInstanceFromRegistry()

Syntax

CreateNewInstanceFromRegistry(PIMoaCacheThis,

PIMoaRegistryEntryDictpRegistryDict,
ConstPMoaInterfaceIDpInterfaceID,
PPMoaVoidppvObj)

Parameters

This
Pointer to the IMoaCache interface

pRegistryDict
PIMoaRegistryEntryDictRegistry dictionary for the class/interface to instantiate

pInterfaceID
ConstPMoaInterfaceIDInterface to return in ppvObj

ppvObj
PPMoaVoidPointer to returned interface

Returns

MoaError

Description


Note: This method is intended more for use in MOA application code than in Xtra code. MOA applications generally determine when and how to create instances of specific Xtra classes and interfaces.

Create an instance of the class and interface cached in the dictionary pRegistryDict and return it in ppvObj. If pInterfaceID is not NULL, that interface will be the one returned in ppvObj; if the class doesn't support that interface, an error is returned. If pInterfaceID is NULL, the interface returned is the one specified in the pRegistryDict.

The interface returned belongs to the caller, who must call Release() on it when done.


EnumerateFileEntries()

Syntax

EnumerateFileEntries(PIMoaCacheThis,

MoaCacheFileEntryEnumProcpEnumProc,
PMoaVoidrefCon)

Parameters

This
Pointer to the IMoaCache interface

pEnumProc
MoaCacheFileEntryEnumProcFile enumeration function

refCon
PMoaVoidPointer to structure for collecting file information

Returns

MoaError

Description

Enumerates all files cached by the application. The cache covers both the application-specific and general Xtras folders, and includes both Xtras and other files found there. The enumeration function you pass in as pEnumProc should have the following syntax:

        typedef MoaError (*MoaCacheFileEntryEnumProc)(
                PIMoaFileEntryDict pFileDict, 
                ConstPMoaSystemFileSpec pFileSpec, 
                MoaWide fileDate, 
                MoaUlong fileType,      /* Mac OS type */
                PMoaVoid refCon); 
        
Your enumeration function will be called repeatedly for each file in the cache. The parameters passed to your function include the file spec, file modification date, and file type (meaningful only on Macintosh systems). The pFileSpec passed is system dependent: it is an FSSpec on the Macintosh and a character string for a pathname on Windows. The refCon passed when you called EnumerateFileEntries() is in turn passed to your enumeration function. You can use refCon to pass a structure pointer into your enumeration function for collecting information about files of interest; if you don't need this pointer, pass NULL . Returning a nonzero value from your enumeration function will terminate the enumeration.

Important note: the pFileSpec passed to you may be NULL.


EnumerateRegistryEntries()

Syntax

EnumerateRegistryEntries(PIMoaCacheThis,

MoaCacheRegistryEntryEnumProcpEnumProc,
PMoaVoidrefCon)

Parameters

This
Pointer to the IMoaCache interface

pEnumProc
MoaCacheRegistryEntryEnumProcRegistry dictionary enumeration function

refCon
PMoaVoidPointer to structure for collecting file information

Returns

MoaError

Description

Call this method to enumerate all registry dictionaries in the cache. The cache contains one registry dictionary for each class/interface provided by Xtras. The enumeration function you pass in as pEnumProc should have the following syntax:

        typedef MoaError (*MoaCacheRegistryEntryEnumProc)(
                PIMoaRegistryEntryDict pRegistryDict, 
                ConstPMoaClassID pClassID, 
                ConstPMoaInterfaceID pInterfaceID, 
                PMoaVoid refCon); 
        
Your procedure will be repeatedly called for each registry in the cache. pRegistryDict provides the registry dictionary for the class/interface combination. pClassID and pInterfaceID provide the class and interface ID of the registered ability. You can use the class/interface pair to create the object. It is generally more convenient to use the pRegistryDict and pInterfaceID parameters to call the IMoaCache methods GetInstanceFromRegistry() or CreateInstanceFromRegistry() to instantiate the particular object and interface.

The refCon passed when you called EnumerateRegistryEntries() is in turn passed to your enumeration function. You can use refCon to pass a structure pointer into your enumeration function for collecting information about classes and interface of interest; if you don't need this pointer, pass NULL . Returning a nonzero value from your enumeration function will terminate the enumeration.


EnumerateRegistryEntriesFromFile()

Syntax

EnumerateRegistryEntriesFromFile(PIMoaCacheThis,

ConstPMoaSystemFileSpecpFileSpec,
MoaLongmaxFolderLevels,
MoaCacheRegistryEntryEnumFromFileProcpEnumProc,
PMoaVoidrefCon)

Parameters

This
Pointer to the IMoaCache interface

pFileSpec
ConstPMoaSystemFileSpecFSSpec on Mac/pathname string in Windows

maxFolderLevels
MoaLongSearch depth

pEnumProc
MoaCacheRegistryEntryEnumFromFileProcRegistry dictionary enumeration function

refCon
PMoaVoidPointer to structure for collecting registry information

Returns

MoaError

Description

Similar to the EnumerateRegistryEntries() method, this method enumerates all registry entries for a specific folder or file. Additional information provided by the enumeration function includes the file and Xtra each came from. The enumeration function you pass in as pEnumProc should have the following syntax:

        typedef MoaError (*MoaCacheRegistryEntryEnumFromFileProc)(
                PIMoaFileEntryDict pFileDict, 
                ConstPMoaSystemFileSpec pFileSpec, 
                MoaWide fileDate, 
                MoaUlong fileType,      /* Mac OS type */
                PIMoaXtraEntryDict pXtraDict, 
                PIMoaRegistryEntryDict pRegistryDict, 
                ConstPMoaClassID pClassID, 
                ConstPMoaInterfaceID pInterfaceID, 
                PMoaVoid refCon); 
        
pFileSpec returned by the enumeration function might be NULL.


EnumerateXtraEntries()

Syntax

EnumerateXtraEntries(PIMoaCacheThis,

MoaCacheXtraEntryEnumProcpEnumProc,
PMoaVoidrefCon)

Parameters

This
Pointer to the IMoaCache interface

pEnumProc
MoaCacheXtraEntryEnumProcXtra dictionary enumeration function

refCon
PMoaVoidPointer to structure for collecting Xtra information

Returns

MoaError

Description

Call this function to enumerate all Xtra dictionaries in the cache. The enumeration function you pass in as pEnumProc should have the following syntax:

        typedef MoaError (*MoaCacheXtraEntryEnumProc)(
                PIMoaXtraEntryDict pXtraDict, 
                PMoaVoid refCon); 
        
Your enumeration function will be called repeatedly for each Xtra in the cache. The parameters passed to your function include the IMoaDict interface to the dictionary for each Xtra. The refCon passed when you called EnumerateXtraEntries() is in turn passed to your enumeration function. You can use refCon to pass a structure pointer into your enumeration function for collecting information about Xtras of interest; if you don't need this pointer, pass NULL . Returning a nonzero value from your enumeration function will terminate the enumeration.


GetFileSpecFromFileDict()

Syntax

GetFileSpecFromFileDict(PIMoaCacheThis,

PIMoaFileEntryDictpFileDict,
PMoaSystemFileSpecpFileSpec,
MoaLongfileSpecLen)

Parameters

This
Pointer to the IMoaCache interface

pFileDict
PIMoaFileEntryDictIMoaDict interface for a particular file entry

pFileSpec
PMoaSystemFileSpecReturned file spec

fileSpecLen
MoaLongLength of returned file spec

Returns

MoaError

Description

Given a file dictionary pFileDict, from either EnumerateFileEntries() or EnumerateRegistryEntriesFromFile(), GetFileSpecFromFileDict() returns the MoaSystemFileSpec associated with it.


GetInstanceFromRegistry()

Syntax

GetInstanceFromRegistry(PIMoaCacheThis,

PIMoaRegistryEntryDictpRegistryDict,
ConstPMoaInterfaceIDpInterfaceID,
PPMoaVoidppvObj)

Parameters

This
Pointer to the IMoaCache interface

pRegistryDict
PIMoaRegistryEntryDictRegistry dictionary for the class/interface to instantiate

pInterfaceID
ConstPMoaInterfaceIDInterface to return in ppvObj

ppvObj
PPMoaVoidPointer to returned interface

Returns

MoaError

Description


Note: This method is intended more for use in MOA application code than in Xtra code. MOA applications generally determine when and how to create instances of specific Xtra classes and interfaces.

Similar to CreateNewInstanceFromRegistry(), this method only creates a new instance of a particular class and interface the first time it is called. Subsequent calls return a new interface (via QueryInterface()) of the same object. The underlying object lives until MOA is shut down (it's kept in an internal table to MOA).

Note that although the object remains in existence, the interface returned belongs to the caller, who still must call Release() it when done.


SetXtraEntryNoncacheable()

Syntax

SetXtraEntryNoncacheable(PIMoaCacheThis,

PIMoaXtraEntryDictpXtraDict)

Parameters

This
Pointer to the IMoaCache interface

pXtraDict
PIMoaXtraEntryDictIMoaDict interface passed to Register() method

Returns

MoaError

Description


Use this method to set the specified Xtra as non-cacheable. This method is provided for use by certain types of Xtras that need to be able to participate in registration each time MOA is started. One such Xtra would be an adapter for non-MOA extensions that needs to check the presence of specific extension file types and cache them independently.

When you call SetXtraEntryNoncacheable() inside an Xtra's Register() method implementation, your Xtra will be registered every time a MOA application is started. The information provided by Register() is analyzed for the current runtime but is never stored in the cache. In general, you shouldn't make an Xtra non-cacheable, since it delays MOA start-up time (and thus app launch time).


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