Поделиться через

Создание примирителей портфеля

  • Статья

Средство согласования портфелем предоставляет портфели средства для согласования различных версий документа.

Сведения о примирителях портфеля

Средство согласования портфеля объединяет различные входные версии документа, чтобы создать одну новую выходную версию документа. Возможно, вам потребуется создать средство согласования портфеля для поддержки вашего типа документа. В этом обзоре описываются выверители портфелем и объясняется, как их создавать.

Рассматриваются следующие темы:

Примирения

Документ — это набор сведений, которые можно скопировать и изменить. Если содержимое по крайней мере двух копий документа отличается, у документа разные версии. При сверки создается одна версия документа из двух или более исходных версий. Как правило, выверяемая версия представляет собой сочетание сведений из исходных версий с самой последней или самой полезной информацией.

Сверка инициируется портфелем, когда определяет, что две или более копии одного документа отличаются. Портфель, который выступает в качестве инициатора в этом контексте, находит и запускает сверку портфеля, связанную с данным типом документа. Средство сверки сравнивает документы и определяет, какие части документов следует сохранить. Для завершения выверки некоторых сверок может потребоваться взаимодействие с пользователем. Другие могут завершить выверку без взаимодействия с пользователем. Средство согласования может содержаться в приложении или быть расширением, реализованным в виде библиотеки DLL.

Некоторые портфели могут создавать остатки. Остаток — это документ, который обычно имеет тот же тип файла, что и исходный документ, который содержит сведения, не сохраненные в объединенной версии. Остатки обычно используются, чтобы дать авторам быстрый способ определить, какие сведения из исходного документа не находятся в окончательной объединенной версии. Если средство согласования поддерживает остатки, он создает по одному остатку для каждой из исходных версий документа. Остатки не создаются, если инициатор не запросит их.

Некоторые выверки портфеля работают с портфелем, чтобы позволить пользователю завершить выверку. Это важная функция для пользователя, который может решить, что выверка не должна продолжаться. Сверка обычно предоставляет объект завершения, когда сверка требует взаимодействия с пользователем и может быть длительной. В некоторых средах сверка может разрешить частичную выверку, что позволяет пользователю временно приостановить сверку и возобновить ее позже. Однако портфель в настоящее время не поддерживает частичную выверку.

Создание примирителя портфеля

Вы можете создать выверку портфеля, реализовав интерфейсы выверки. Как минимум, средство согласования реализует интерфейс IReconcilableObject и интерфейс IPersistStorage или IPersistFile . В качестве инициатора портфель определяет, когда требуется сверка, и вызывает метод IReconcilableObject::Reconcile для инициирования выверки.

Хотя IReconcilableObject::Reconcile предоставляет широкий набор возможностей выверки, в большинстве случаев выверка портфеля выполняет лишь минимальную выверку. В частности, для портфеля не требуется, чтобы выверщик поддерживал создание остатков или поддерживал объект завершения. Кроме того, выверка выполняет одну выверку сверху вниз и не должна возвращать REC_E_NOTCOMPLETE значение; то есть не следует пытаться выполнить частичное выверку.

Портфель предоставляет интерфейс IReconcileInitiator . Средство согласования портфеля может использовать метод IReconcileInitiator::SetAbortCallback для задания объекта завершения. Портфель не использует идентификаторы версий и поэтому не может предоставить предыдущие версии документа, если выверитель запрашивает их с помощью соответствующих методов в IReconcileInitiator.

Портфель передается в моникеры файла IReconcilableObject::Reconcile , представляющие версии документа для согласования. Выверка портфеля получает доступ к версиям с помощью метода IMoniker::BindToObject или IMoniker::BindToStorage . Последнее, как правило, быстрее и рекомендуется. Средство согласования должно освободить все объекты или хранилище, к которым он привязывается.

Когда средство согласования портфеля использует IMoniker::BindToStorage, оно привязывается к хранилищу, которое является либо неструктурированным хранилищем (потоком), либо структурированным хранилищем, определенным OLE. Если средство согласования ожидает неструктурированное хранилище, он должен использовать IMoniker::BindToStorage для запроса интерфейса IStream . Если средство согласования ожидает структурированное хранилище, он должен запросить интерфейс IStorage . В обоих случаях он должен запрашивать прямой (нетрансляционный) доступ к хранилищу только для чтения; Доступ на чтение и запись может быть недоступен.

Средство согласования с минимальным портфелем обычно напрямую рассматривает хранилище других версий и работает с внедренными объектами очень примитивно, например слияние двух версий объекта путем включения обеих версий в выходную версию.

Инициатор находит соответствующий выверщик портфеля, используя подмножество логики, реализованной функцией GetClassFile , чтобы определить тип заданного файла, а затем ищет в реестре класс сверки, связанный с данным типом файла. Портфель, как и другие компоненты оболочки, определяет тип файла исключительно по расширению имени файла. Расширение файла должно иметь зарегистрированный тип файла для портфеля, чтобы вызвать средство согласования для файла. При установке сверки необходимо задать запись реестра следующей формы.

CLSID
   {the file CLSID}
      Roles
         Reconciler
            (Default) = {the reconciler-classid}

Класс должен быстро загружаться, должен быть назначен _MULTIPLEUSE и, если для интерфейса выверки не предоставлены маршалеры, должен быть внутрипроцессным сервером (содержащимся в БИБЛИОТЕКе DLL), а не локальным сервером (реализованным в файле .exe).

Взаимодействие с пользователем при выверке

Выверка портфеля должна пытаться выполнить выверку без взаимодействия с пользователем. Чем более автоматизирована выверка, тем лучше пользователь воспринимает процесс.

В некоторых случаях вмешательство пользователя может быть полезным. Например, система документов может потребовать от пользователя просмотреть изменения перед принятием объединенной версии документа или потребовать от пользователя комментариев, объясняющих внесенные изменения. В таких случаях инициатор, а не выверитель портфеля, отвечает за запрос пользователя и выполнение его инструкций.

В других случаях может потребоваться вмешательство пользователя, например, если две версии были изменены несовместимыми способами. В таких случаях инициатор или выверщик портфеля должны запросить у пользователя инструкции по устранению конфликта. Как правило, ни инициатор не может полагаться на завершение выверки, не ожидая какого-то взаимодействия с пользователем. С другой стороны, вы можете взаимодействовать с пользователем для разрешения конфликтов или требовать от инициатора этого.

Выверка внедренных объектов

При сверке документа сам выверщик портфеля может стать инициатором, если обнаруживает внедренный объект типа, который он не может выверить. В этом случае посреднику необходимо рекурсивно выверять каждый из внедренных объектов и взять на себя все обязанности инициатора.

Для выполнения рекурсии выверка портфеля загружает объект и запрашивает соответствующий интерфейс. Обработчик объекта должен поддерживать интерфейс . Если какой-либо метод интерфейса возвращает значение OLE_E_NOTRUNNING, то для выполнения операции средство согласования должно запустить объект . Так как код для внедренных объектов не всегда доступен, средство согласования должно предоставить решение для этого условия. Например, средство согласования может включать как старую, так и новую версии внедренного объекта в выверяемую версию. Сверка не должна пытаться выполнить согласование между связями.

Инициатор хранит объединяемые версии документов. Во многих случаях инициатор имеет доступ к хранилищу каждой версии и сохраняет результат выверки с помощью аналогичного хранилища. Однако иногда инициатор может иметь объект в памяти, для которого не доступна постоянная версия. Такая ситуация может возникнуть, когда документ, содержащий открытые внедренные объекты, должен быть согласован перед сохранением. В таких случаях инициатор сохраняет результат выверки в версии, найденной в памяти.

Инициатор использует интерфейс IPersistStorage для привязки (загрузки) объединенной версии. Инициатор использует метод IPersistStorage::Load , если начальная версия уже создана, и использует метод IPersistStorage::InitNew для начальной версии. При загрузке объединенной версии инициатор использует QueryInterface для получения адреса интерфейса IReconcilableObject . Этот интерфейс предоставляет инициатору доступ к хранилищу существующих остатков и позволяет создать хранилище для любых новых остатков. Затем инициатор направляет интерфейс для выполнения выверки. Инициатор фактически запрашивает интерфейс IPersistFile перед IPersistStorage. Если средство согласования поддерживает IPersistFile, инициатор управляет реплика с помощью методов IPersistFile, а не IPersistStorage. Это позволяет выверка файлов, которые не хранятся в виде составных документов.

После завершения выверки инициатор может сохранить объединенную версию с помощью интерфейса IPersistStorage или IPersistFile . Во время выверки средство выверки портфеля создает остатки по мере необходимости и записывает их постоянные биты в хранилище. Если объединенная версия является потоком, интерфейс IStorage , передаваемый в IPersistStorage::Load , содержит поток с именем "Содержимое" с состоянием хранения, равным STATEBITS_FLAT. (Биты состояния можно задать с помощью метода IStorage::Stat .) После слияния инициатор сохраняет объединенную версию, записывая данные соответствующим образом. Он должен убедиться, что STATEBITS_FLAT задан соответствующим образом для хранилища.

Остатков

Инициатор указывает, требуется ли ему остатки, задавая параметру pstgNewResidues допустимый адрес при вызове метода IReconcilableObject::Reconcile . Если средство согласования не поддерживает создание остатков, оно должно немедленно возвращать значение REC_E_NORESIDUES, если параметр dwFlags не указывает значение RECONCILEF_NORESIDUESOK .

Выверка портфеля возвращает остатки инициатору путем создания новых элементов хранения и их копирования в массив, на который указывает pstgNewResidues. Для структурированных остатков хранилища выверка копирует интерфейс IStorage , а для остатков неструктурированного хранения копирует интерфейс IStream или IStorage с установленным флагом STATEBITS_FLAT. Средство согласования использует IStorage для создания необходимого хранилища, используя IStorage::CreateStream для создания плоского хранилища для остатков, которые являются потоком, и IStorage::CreateStorage для создания структурированного хранилища.

Инициатор подготавливает pstgNewResidues , чтобы он не содержал элементов в незарезервированной части пространства имен IStorage . Выверка портфеля помещает каждый остаток в элемент, имя которого соответствует порядку его первоначальной версии. Например, первый остаток содержится в "1", второй в "2" и т. д. Если выверяемый объект сам создает остаток, он обнаруживается в элементе с именем "0".

Средство согласования портфеля фиксирует каждый из вновь созданных элементов по отдельности, гарантируя, что инициатор имеет доступ к информации. Однако при согласовании pstgNewResidues не фиксируется . Инициатор несет ответственность за фиксацию этого или иным способом его ликвидацию.

Справочник по выверщику портфеля

В этом разделе содержатся сведения об интерфейсах выверки. При обработке ошибок метод может возвращать только те значения ошибок, которые явно определены в качестве возможных возвращаемых значений. Кроме того, перед возвратом из ошибки метод должен задать для всех переменных, адреса которых передаются в качестве параметров.

Интерфейсы и методы выверки портфеля