Creating a Briefcase Reconciler

You create a briefcase reconciler by implementing the reconciliation interfaces. At a minimum, a reconciler implements the IReconcilableObject interface and the IPersistStorage or IPersistFile interface. As the initiator, the Briefcase determines when reconciliation is needed and calls the IReconcilableObject::Reconcile member function to initiate reconciliation.

Although the Reconcile member function can provide a wide-ranging set of reconciliation capabilities, a briefcase reconciler carries out only minimal reconciliation in most cases. In particular, the Briefcase does not require the reconciler to support residue generation or to support the termination object. Also, the reconciler carries out a single top to bottom reconciliation and must not return the REC_E_NOTCOMPLETE value; that is, it should not attempt partial reconciliation.

The Briefcase provides the IReconcileInitiator interface. The briefcase reconciler can use the IReconcileInitiator::SetAbortCallback member function to set the termination object. The Briefcase does not use version identifiers and can, therefore, not provide previous versions of a document if a reconciler requests them using the corresponding member functions in IReconcileInitiator.

The Briefcase passes file monikers to Reconcile representing the versions of the document to be reconciled. The briefcase reconciler gains access to the versions by using either the IMoniker::BindToObject or IMoniker::BindToStorage member function. The latter is generally faster and is recommended. The reconciler must release any objects or storage to which it binds.

When the briefcase reconciler uses BindToStorage, it binds to storage that is either flat storage (a stream) or OLE-defined structured storage. If the reconciler expects flat storage, it should use BindToStorage to request the IStream interface. If the reconciler expects structured storage, it should request the IStorage interface. In both cases, it should request read-only direct (nontransacted) access to the storage; read-write access may not generally be available.

A minimal briefcase reconciler typically looks directly at the storage of the other versions and deals with embedded objects in a very primitive manner, such as merging two versions of the object by including both versions in the output version.

The initiator locates the appropriate briefcase reconciler by using a subset of the logic implemented by the GetClassFile function to determine the class of a given file and then looks in the registry for the reconciler class associated with the given file class. The Briefcase, like other shell components, determines the class of a file solely by the filename extension. A file's extension must have a registered class for the Briefcase to invoke a reconciler for the file. You must set a registry entry of the following form when installing your reconciler.

CLSID\clsid\Roles\Reconciler\reconciler-classid

The class must be quick loading, must be designated _MULTIPLEUSE, and, unless marshallers are provided for the reconciliation interface, must be an in-process server (contained in a DLL) rather than a local server (implemented in an .EXE file).