Persistent Handlers

[This is preliminary documentation and subject to change.]

Microsoft® Index Server assumes implementations of the IFilter interface are registered as persistent handlers for OLE classes. The specifics of the persistent handler mechanism may change in future releases of Windows NT® or Index Server, but the API described below will continue to be supported.

A persistent handler provides the same service for the persistent image of an object that the OLE running object table provides for the loaded, in-memory image. The persistent handler is the broker between the persistent state of an object and clients wishing to access that state. It is responsible for coordinating multiple client access to the persistent state of an object.

Multiple handlers may be defined to provide behavior for a single persistent object. Each interface may specify a unique handler for only that interface. Potentially, multiple handlers which are ignorant of each other may all operate on the persistent image of the same object. It is the responsibility of the persistent handler to load the correct implementation for each interface.

The following registry entries are sufficient to load the implementation of IFilter for objects of type SampleObject.

\Registry\MACHINE\SOFTWARE\Classes
 
    .sam
        = REG_SZ SampleFile
 
    SampleFile
        = REG_SZ Class for Sample Files
        CLSID
           = REG_SZ {40A45370-0386-11D0-AE19-00AA004B9986}
    CLSID
        {40A45370-0386-11D0-AE19-00AA004B9986}
           = REG_SZ Sample Files
           InprocServer32
              = REG_SZ sample.dll
           PersistentHandler
               = REG_SZ {A6317C60-0386-11D0-AE19-00AA004B9986}
 
        {A6317C60-0386-11D0-AE19-00AA004B9986}
           = REG_SZ Sample file persistent handler
           PersistentAddinsRegistered
              {89BCB740-6119-101A-BCB7-00DD010655AF}
                 = REG_SZ {D7455400-0386-11D0-AE19-00AA004B9986}
 
        {D7455400-0386-11D0-AE19-00AA004B9986}
           = REG_SZ C and C++ filter
           InprocServer32
              = REG_SZ sampfilt.dll
              ThreadingModel = Apartment
 

Up through the entry for the class (CLSID\40A45370-0386-11D0-AE19-00AA004B9986), these entries are standard OLE registry entries. The DLL sample.dll implements running object behavior for the .sam class. But note the extra entry, PersistentHandler. This entry specifies the class responsible for brokering requests to the persistent objects of the sample class. The entry under PersistentAddinsRegistered identifies the implementation responsible for the interface named 89BCB740-6119-101A-BCB7-00DD010655AF (IID_IFilter). Finally, we come to the class implementing IID_IFilter and again, the entries are standard OLE registry entries. The InprocServer32 is loaded through the standard OLE mechanism. Microsoft Index Server observes the threading model specified for the filter. When the threading model is Both, the filter must be thread safe. If the filter is not thread safe, specify Apartment.