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()
Syntax
-
- AddRegistryEntry(PIMoaCacheThis,
PIMoaXtraEntryDictpXtraDict,
ConstPMoaClassIDpClassID,
ConstPMoaInterfaceIDpInterfaceID,
PIMoaRegistryEntryDict FAR *ppRegistryDict)
Parameters
-
This
- Pointer to the
IMoaCache
interface
pXtraDict
PIMoaXtraEntryDict
IMoaDict instance for the Xtra dictionary
pClassID
ConstPMoaClassID
CLSID of the class being registered
pInterfaceID
ConstPMoaInterfaceID
IID 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.
Syntax
-
- CreateNewInstanceFromRegistry(PIMoaCacheThis,
PIMoaRegistryEntryDictpRegistryDict,
ConstPMoaInterfaceIDpInterfaceID,
PPMoaVoidppvObj)
Parameters
-
This
- Pointer to the
IMoaCache
interface
pRegistryDict
PIMoaRegistryEntryDict
Registry dictionary for
the class/interface to instantiate
pInterfaceID
ConstPMoaInterfaceID
Interface to return in ppvObj
ppvObj
PPMoaVoid
Pointer 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.
Syntax
-
- EnumerateFileEntries(PIMoaCacheThis,
MoaCacheFileEntryEnumProcpEnumProc,
PMoaVoidrefCon)
Parameters
-
This
- Pointer to the
IMoaCache
interface
pEnumProc
MoaCacheFileEntryEnumProc
File enumeration function
refCon
PMoaVoid
Pointer 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.
Syntax
-
- EnumerateRegistryEntries(PIMoaCacheThis,
MoaCacheRegistryEntryEnumProcpEnumProc,
PMoaVoidrefCon)
Parameters
-
This
- Pointer to the
IMoaCache
interface
pEnumProc
MoaCacheRegistryEntryEnumProc
Registry dictionary
enumeration function
refCon
PMoaVoid
Pointer 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.
Syntax
-
- EnumerateRegistryEntriesFromFile(PIMoaCacheThis,
ConstPMoaSystemFileSpecpFileSpec,
MoaLongmaxFolderLevels,
MoaCacheRegistryEntryEnumFromFileProcpEnumProc,
PMoaVoidrefCon)
Parameters
-
This
- Pointer to the
IMoaCache
interface
pFileSpec
ConstPMoaSystemFileSpec
FSSpec on Mac/pathname
string in Windows
maxFolderLevels
MoaLong
Search depth
pEnumProc
MoaCacheRegistryEntryEnumFromFileProc
Registry
dictionary enumeration function
refCon
PMoaVoid
Pointer 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.
Syntax
-
- EnumerateXtraEntries(PIMoaCacheThis,
MoaCacheXtraEntryEnumProcpEnumProc,
PMoaVoidrefCon)
Parameters
-
This
- Pointer to the
IMoaCache
interface
pEnumProc
MoaCacheXtraEntryEnumProc
Xtra dictionary enumeration
function
refCon
PMoaVoid
Pointer 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.
Syntax
-
- GetFileSpecFromFileDict(PIMoaCacheThis,
PIMoaFileEntryDictpFileDict,
PMoaSystemFileSpecpFileSpec,
MoaLongfileSpecLen)
Parameters
-
This
- Pointer to the
IMoaCache
interface
pFileDict
PIMoaFileEntryDict
IMoaDict interface for a particular file entry
pFileSpec
PMoaSystemFileSpec
Returned file spec
fileSpecLen
MoaLong
Length of returned file spec
Returns
-
MoaError
Description
-
- Given a file dictionary pFileDict,
from either EnumerateFileEntries() or EnumerateRegistryEntriesFromFile(), GetFileSpecFromFileDict() returns
the MoaSystemFileSpec associated with it.
Syntax
-
- GetInstanceFromRegistry(PIMoaCacheThis,
PIMoaRegistryEntryDictpRegistryDict,
ConstPMoaInterfaceIDpInterfaceID,
PPMoaVoidppvObj)
Parameters
-
This
- Pointer to the
IMoaCache
interface
pRegistryDict
PIMoaRegistryEntryDict
Registry dictionary for
the class/interface to instantiate
pInterfaceID
ConstPMoaInterfaceID
Interface to return in ppvObj
ppvObj
PPMoaVoid
Pointer 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.
Syntax
-
- SetXtraEntryNoncacheable(PIMoaCacheThis,
PIMoaXtraEntryDictpXtraDict)
Parameters
-
This
- Pointer to the
IMoaCache
interface
pXtraDict
PIMoaXtraEntryDict
IMoaDict 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.