Erstellen von Aktenkofferabgleichen
Ein Aktenkoffer-Abgleich gibt der Aktentasche die Möglichkeit, verschiedene Versionen eines Dokuments zu vereinbaren.
Informationen zu Aktenkofferabsöhnern
Ein Aktenkoffer-Abgleich kombiniert verschiedene Eingabeversionen eines Dokuments, um eine einzelne, neue Ausgabeversion des Dokuments zu erzeugen. Möglicherweise müssen Sie einen Aktenkoffer-Abgleich erstellen, um Ihren Dokumenttyp zu unterstützen. In dieser Übersicht werden Aktenkofferabgleiche und deren Erstellung beschrieben.
Die folgenden Themen werden erörtert:
- Versöhnung
- Erstellen eines Aktenkoffer-Abgleichs
- Benutzerinteraktion in der Abstimmung
- Abgleich eingebetteter Objekte
- Rückstände
Versöhnung
Ein Dokument ist eine Sammlung von Informationen, die kopiert und geändert werden können. Ein Dokument hat unterschiedliche Versionen, wenn der Inhalt von mindestens zwei Kopien des Dokuments unterschiedlich ist. Die Abstimmung erzeugt eine einzelne Version eines Dokuments aus zwei oder mehr Anfangsversionen. In der Regel ist die abgeglichene Version eine Kombination aus Informationen aus den ersten Versionen mit den neuesten oder nützlichsten Informationen, die beibehalten werden.
Die Abstimmung wird durch Den Aktenkoffer initiiert, wenn festgestellt wird, dass zwei oder mehr Kopien desselben Dokuments unterschiedlich sind. Die Aktentasche, die in diesem Kontext als Initiator fungiert, sucht und startet den Aktenkoffer-Abgleich, der dem angegebenen Dokumenttyp zugeordnet ist. Der Abgleich vergleicht die Dokumente und bestimmt, welche Teile der Dokumente aufbewahrt werden sollen. Einige Abgleiche erfordern möglicherweise eine Benutzerinteraktion, um die Abstimmung abzuschließen. Andere können die Abstimmung ohne Benutzerinteraktion abschließen. Der Abgleich kann in einer Anwendung enthalten sein oder eine Erweiterung sein, die als DLL implementiert ist.
Einige Aktenkoffer-Abgleiche können Rückstände erzeugen. Ein Rückstand ist ein Dokument, das in der Regel denselben Dateityp wie das ursprüngliche Dokument aufweist und Informationen enthält, die nicht in der zusammengeführten Version gespeichert wurden. Rückstände werden in der Regel verwendet, um Autoren eine schnelle Möglichkeit zu geben, zu bestimmen, welche Informationen aus ihrem Ursprünglichen Dokument in der endgültigen zusammengeführten Version nicht enthalten sind. Wenn ein Abgleich Rückstände unterstützt, erzeugt er einen Rückstand für jede originale Version des Dokuments. Rückstände werden nur erstellt, wenn der Initiator sie anfordert.
Einige Aktenkofferabgleiche arbeiten mit Aktentasche, damit der Benutzer die Abstimmung beenden kann. Dies ist ein wichtiges Feature für einen Benutzer, der entscheiden kann, dass die Abstimmung nicht fortgesetzt werden soll. Ein Abgleich stellt in der Regel ein Terminierungsobjekt bereit, wenn die Abstimmung eine Benutzerinteraktion erfordert und möglicherweise langwierig ist. In einigen Umgebungen kann ein Abgleich einen teilweisen Abgleich ermöglichen, sodass ein Benutzer eine Abstimmung vorübergehend aussetzen und später fortsetzen kann. Die Aktentasche unterstützt derzeit jedoch keine teilweise Abstimmung.
Erstellen eines Aktenkoffer-Abgleichs
Sie erstellen einen Aktenkoffer-Abgleich, indem Sie die Abstimmungsschnittstellen implementieren. Mindestens implementiert ein Versöhner die IReconcilableObject-Schnittstelle und die IPersistStorage - oder IPersistFile-Schnittstelle . Als Initiator bestimmt Die Aktentasche, wann eine Abstimmung erforderlich ist, und ruft die IReconcilableObject::Reconciliation-Methode auf, um die Abstimmung zu initiieren.
Obwohl IReconcilableObject::Reconciliation eine breite Palette von Abstimmungsfunktionen bietet, führt ein Aktenkofferabgleich in den meisten Fällen nur eine minimale Abstimmung durch. Insbesondere erfordert Die Aktentasche den Abgleich nicht, um die Generierung von Rückständen zu unterstützen oder das Beendigungsobjekt zu unterstützen. Außerdem führt der Versöhner eine einzige Abstimmung von oben nach unten durch und darf den REC_E_NOTCOMPLETE Wert nicht zurückgeben. das heißt, es sollte nicht versucht werden, eine teilweise Versöhnung zu versuchen.
Briefcase stellt die IReconcileInitiator-Schnittstelle bereit . Der Aktenkofferabgleich kann die IReconcileInitiator::SetAbortCallback-Methode verwenden, um das Terminierungsobjekt festzulegen. Die Aktentasche verwendet keine Versionsbezeichner und kann daher keine früheren Versionen eines Dokuments bereitstellen, wenn sie von einem Abgleich mit den entsprechenden Methoden in IReconcileInitiator angefordert werden.
Aktenkoffer wird an IReconcilableObject::Versöhnen der Dateimoniker übergeben, die die Versionen des dokuments darstellen, die abgeglichen werden sollen. Der Aktenkoffer-Abgleich erhält Zugriff auf die Versionen, indem er entweder die IMoniker::BindToObject - oder IMoniker::BindToStorage-Methode verwendet. Letzteres ist in der Regel schneller und wird empfohlen. Der Abgleich muss alle Objekte oder Speicher freigeben, an die er gebunden ist.
Wenn der Aktenkoffer-Abgleich IMoniker::BindToStorage verwendet, bindet er an Speicher, der entweder flat Storage (ein Stream) oder OLE-definierter strukturierter Speicher ist. Wenn der Versöhner einen flachen Speicher erwartet, sollte er IMoniker::BindToStorage verwenden, um die IStream-Schnittstelle anzufordern. Wenn der Versöhner einen strukturierten Speicher erwartet, sollte er die IStorage-Schnittstelle anfordern. In beiden Fällen sollte sie schreibgeschützten direkten (nicht übersetzten) Zugriff auf den Speicher anfordern. Lese-/Schreibzugriff ist möglicherweise nicht verfügbar.
Ein minimaler Aktenkoffer-Abgleich befasst sich in der Regel direkt mit der Speicherung der anderen Versionen und behandelt eingebettete Objekte auf sehr primitive Weise, z. B. das Zusammenführen von zwei Versionen des Objekts, indem beide Versionen in die Ausgabeversion eingeschlossen werden.
Der Initiator sucht den entsprechenden Aktenkoffer-Abgleich mithilfe einer Teilmenge der Logik, die von der GetClassFile-Funktion implementiert wurde, um den Typ einer bestimmten Datei zu bestimmen, und sucht dann in der Registrierung nach der Dem angegebenen Dateityp zugeordneten Abgleichsklasse. Die Aktentasche bestimmt wie andere Shellkomponenten den Typ einer Datei ausschließlich durch die Dateinamenerweiterung. Die Erweiterung einer Datei muss einen registrierten Dateityp für Aktenkoffer aufweisen, um einen Abgleich für die Datei aufzurufen. Sie müssen einen Registrierungseintrag des folgenden Formulars festlegen, wenn Sie Ihren Abgleich installieren.
CLSID
{the file CLSID}
Roles
Reconciler
(Default) = {the reconciler-classid}
Die Klasse muss schnell geladen werden, muss _MULTIPLEUSE festgelegt werden und muss, sofern keine Marshaller für die Abstimmungsschnittstelle bereitgestellt werden, ein Prozessserver (in einer DLL enthalten) und nicht ein lokaler Server (implementiert in einer .exe-Datei) sein.
Benutzerinteraktion in der Abstimmung
Ein Aktenkoffer-Abgleich sollte versuchen, die Abstimmung ohne Benutzerinteraktion durchzuführen. Je automatisierter die Abstimmung, desto besser ist die Wahrnehmung des Prozesses durch den Benutzer.
In einigen Fällen kann der Benutzereingriff wertvoll sein. Beispielsweise kann ein Dokumentsystem erfordern, dass ein Benutzer Änderungen überprüfen muss, bevor er die zusammengeführte Version eines Dokuments akzeptiert, oder es kann kommentare vom Benutzer erforderlich sein, die die vorgenommenen Änderungen erläutern. In diesen Fällen ist der Initiator, nicht der Aktenkoffer-Abgleich, für die Abfrage des Benutzers und die Ausführung der Anweisungen des Benutzers verantwortlich.
In anderen Fällen kann ein Benutzereingriff erforderlich sein, z. B. wenn zwei Versionen auf inkompatible Weise bearbeitet wurden. In solchen Fällen muss entweder der Initiator oder der Aktenkoffer-Abgleich den Benutzer abfragen, um Anweisungen zum Lösen des Konflikts zu erhalten. Im Allgemeinen kann sich kein Initiator darauf verlassen, eine Abstimmung abzuschließen, ohne eine Benutzerinteraktion zu erwarten. Versöhner hingegen haben die Möglichkeit, mit dem Benutzer zu interagieren, um Konflikte zu lösen oder den Initiator dazu zu verpflichten.
Abgleich eingebetteter Objekte
Beim Abgleichen eines Dokuments kann der Aktenkoffer-Abgleich selbst zum Initiator werden, wenn er ein eingebettetes Objekt eines Typs erkennt, das er nicht versöhnen kann. In diesem Fall muss der Abgleich jedes der eingebetteten Objekte rekursiv abgleichen und alle Verantwortlichkeiten eines Initiators übernehmen.
Um die Rekursion durchzuführen, lädt der Aktenkoffer-Abgleich das Objekt und fragt die entsprechende Schnittstelle ab. Der Handler für das -Objekt muss die Schnittstelle unterstützen. Wenn eine Methode der Schnittstelle den OLE_E_NOTRUNNING Wert zurückgibt, muss der Versöhner das Objekt ausführen, um den Vorgang auszuführen. Da Code für eingebettete Objekte nicht immer verfügbar ist, muss ein Abgleich eine Lösung für diese Bedingung bereitstellen. Beispielsweise kann der Abgleich sowohl alte als auch neue Versionen des eingebetteten Objekts in der abgeglichenen Version enthalten. Der Versöhner darf nicht versuchen, linksübergreifend zu versöhnen.
Der Initiator speichert die zusammengeführten Dokumentversionen. In vielen Fällen hat der Initiator Zugriff auf den Speicher jeder Version und speichert das Ergebnis der Abstimmung mithilfe eines ähnlichen Speichers. Manchmal kann der Initiator jedoch über ein Im-Memory-Objekt verfügen, für das keine persistente Version verfügbar ist. Diese Situation kann auftreten, wenn ein Dokument, das offene eingebettete Objekte enthält, vor dem Speichern abgeglichen werden muss. In solchen Fällen speichert der Initiator das Ergebnis der Abstimmung in der Version, die im Arbeitsspeicher gefunden wurde.
Der Initiator verwendet die IPersistStorage-Schnittstelle , um die zusammengeführte Version zu binden (zu laden). Der Initiator verwendet die IPersistStorage::Load-Methode , wenn bereits eine erste Version erstellt wurde, und verwendet die IPersistStorage::InitNew-Methode für die erste Version. Wenn die zusammengeführte Version geladen wird, verwendet der Initiator QueryInterface , um die Adresse der IReconcilableObject-Schnittstelle abzurufen. Diese Schnittstelle gibt dem Initiator Zugriff auf die Lagerung der vorhandenen Rückstände und ermöglicht es, eine Lagerung für alle neuen Rückstände zu erstellen. Anschließend leitet der Initiator die Schnittstelle an, die Abstimmung durchzuführen. Der Initiator fragt tatsächlich die IPersistFile-Schnittstelle vor IPersistStorage ab. Wenn der Versöhner IPersistFile unterstützt, bearbeitet der Initiator das Replikat über die IPersistFile-Methode und nicht über die IPersistStorage-Methoden. Dies ermöglicht den Abgleich von Dateien, die nicht als zusammengesetzte Dokumente gespeichert sind.
Wenn die Abstimmung abgeschlossen ist, kann der Initiator die zusammengeführte Version mithilfe der IPersistStorage - oder IPersistFile-Schnittstelle speichern. Während der Abstimmung erzeugt der Aktenkoffer-Abgleich bei Bedarf Rückstände und schreibt ihre persistenten Bits in den Speicher. Wenn es sich bei der zusammengeführten Version um einen Stream handelt, enthält die an IPersistStorage::Load übergebene IStorage-Schnittstelle einen Stream namens "Contents", dessen Speicherstatus auf STATEBITS_FLAT festgelegt ist. (Sie können die Zustandsbits mit der IStorage::Stat-Methode festlegen.) Nach der Zusammenführung speichert der Initiator die zusammengeführte Version, indem er die Daten in geeigneter Weise schreibt. Sie sollte sicherstellen, dass STATEBITS_FLAT für den Speicher entsprechend festgelegt wird.
Rückstände
Der Initiator gibt an, ob er Rückstände wünscht, indem er beim Aufrufen der IReconcilableObject::Reconcile-Methode den pstgNewResidues-Parameter auf eine gültige Adresse festlegt. Wenn der Abgleich die Erstellung von Rückständen nicht unterstützt, muss er sofort den REC_E_NORESIDUES Wert zurückgeben, es sei denn, der dwFlags-Parameter gibt den RECONCILEF_NORESIDUESOK Wert an.
Der Aktenkoffer-Abgleich gibt Rückstände an den Initiator zurück, indem neue Speicherelemente erstellt und in das Array kopiert werden, auf das von pstgNewResidues verwiesen wird. Bei strukturierten Speicherrückständen kopiert der Abgleich eine IStorage-Schnittstelle , und für flache Speicherrückstände kopiert er entweder eine IStream - oder eine IStorage-Schnittstelle mit dem STATEBITS_FLAT-Flag. Der Abgleich verwendet IStorage, um den erforderlichen Speicher zu erstellen, wobei IStorage::CreateStream verwendet wird, um flachen Speicher für einen Rückstand zu erstellen, der ein Stream ist, und IStorage::CreateStorage , um strukturierten Speicher zu erstellen.
Der Initiator bereitet pstgNewResidues so vor, dass es keine Elemente im nicht reservierten Teil des IStorage-Namespace enthält. Der Aktenkoffer-Abgleich platziert jeden Rückstand in einem Element, dessen Name der Reihenfolge der ursprünglichen Version entspricht. Beispielsweise ist der erste Rückstand in "1", der zweite in "2" usw. enthalten. Wenn das abgeglichene Objekt selbst einen Rückstand erzeugt, befindet es sich im Element mit dem Namen "0".
Der Aktenkoffer-Abgleich committ jedes neu erstellte Element einzeln, um sicherzustellen, dass der Initiator Zugriff auf die Informationen hat. Der Versöhner committ jedoch nicht pstgNewResidues selbst. Der Initiator ist dafür verantwortlich, dies zu übernehmen oder anderweitig zu veräußern.
Referenz zum Aktenkoffer-Abgleich
Dieser Abschnitt enthält Informationen zu den Abstimmungsschnittstellen. Bei der Behandlung von Fehlern kann eine Methode nur die Fehlerwerte zurückgeben, die explizit als mögliche Rückgabewerte definiert sind. Darüber hinaus muss die -Methode alle Variablen, deren Adressen als Parameter übergeben werden, auf NULL festlegen, bevor sie vom Fehler zurückgegeben werden.
Schnittstellen und Methoden zum Abgleich von Aktenkoffern