Briefcase リコンサイザーの作成
Briefcase リコンサイルは、さまざまなバージョンのドキュメントを調整する手段を Briefcase に提供します。
Briefcase リコンサイザーについて
briefcase リコンサイルは、ドキュメントのさまざまな入力バージョンを組み合わせて、ドキュメントの単一の新しい出力バージョンを生成します。 ドキュメントの種類をサポートするには、briefcase リコンサイル機能を作成することが必要な場合があります。 この概要では、briefcase リコンサイル機能について説明し、その作成方法について説明します。
検討されているトピックは、次のとおりです。
和解
ドキュメントは、コピーおよび変更できる情報のコレクションです。 ドキュメントの少なくとも 2 つのコピーの内容が異なる場合、ドキュメントのバージョンが異なります。 調整では、2 つ以上の初期バージョンから 1 つのバージョンのドキュメントが生成されます。 通常、リコンサイルされたバージョンは、初期バージョンの情報と、最新または最も有用な情報が保持された組み合わせです。
調整は、同じ文書の 2 つ以上のコピーが異なると判断されたときに、Briefcase によって開始されます。 このコンテキストでイニシエーターとして機能する Briefcase は、指定されたドキュメントの種類に関連付けられている briefcase リコンサイルを検索して開始します。 リコンサイザーは、ドキュメントを比較し、保持するドキュメントの部分を決定します。 一部のリコンサイルでは、調整を完了するためにユーザーの操作が必要になる場合があります。 他のユーザーは、ユーザーの操作なしで調整を完了する可能性があります。 リコンサイル機能は、アプリケーション内に格納することも、DLL として実装される拡張機能にすることもできます。
一部のブリーフケースリコンサイルでは、残留物が作成される場合があります。 残渣は、通常、差し込み印刷されたバージョンに保存されていない情報を含む、初期ドキュメントと同じファイルの種類を持つドキュメントです。 通常、残渣は、元のドキュメントの情報が最終的なマージ バージョンに含まれていないものを作成者に簡単に判断するために使用されます。 リコンサイルが残基をサポートしている場合、ドキュメントの元のバージョンごとに 1 つの残基が作成されます。 イニシエーターが要求しない限り、残渣は作成されません。
一部の briefcase リコンサイルは、ユーザーが調整を終了できるように、Briefcase と連携します。 これは、調整を続行すべきでないと判断するユーザーにとって重要な機能です。 リコンサイルは、通常、調整にユーザーの操作が必要であり、時間がかかる場合に終了オブジェクトを提供します。 一部の環境では、調整者が部分的な調整を許可し、ユーザーが調整を一時的に中断して後で再開できるようにする場合があります。 ただし、現在、Briefcase では部分的な調整はサポートされていません。
Briefcase リコンサイルャーの作成
調整インターフェイスを実装して、briefcase リコンサイルを作成します。 少なくとも、リコンサイル機能は IReconcilableObject インターフェイスと IPersistStorage または IPersistFile インターフェイスを 実装します。 イニシエーターとして、Briefcase は調整が必要なタイミングを決定し、 IReconcilableObject::Reconcile メソッドを呼び出して調整を開始します。
IReconcilableObject::Reconcile には幅広い調整機能セットが用意されていますが、ほとんどの場合、ブリーフケースリコンサイルでは最小限の調整のみが実行されます。 特に、Briefcase では、残留物の生成をサポートしたり終了オブジェクトをサポートしたりするためにリコンサイルを必要としません。 また、調整者は上から下への調整を 1 回実行し、REC_E_NOTCOMPLETE値を返してはなりません。つまり、部分的な調整を試みてはなりません。
Briefcase には、 IReconcileInitiator インターフェイスが用意されています。 briefcase リコンサイルでは、 IReconcileInitiator::SetAbortCallback メソッドを使用して終了オブジェクトを設定できます。 Briefcase はバージョン識別子を使用しないため、リコンサイザーが IReconcileInitiator の対応するメソッドを使用してドキュメントを要求した場合は、以前のバージョンのドキュメントを提供できません。
Briefcase は、調整するドキュメントのバージョンを表すファイル モニカーを IReconcilableObject::Reconcile に渡します。 briefcase リコンサイルは、IMoniker::BindToObject メソッドまたは IMoniker::BindToStorage メソッドを使用してバージョンにアクセスできます。 後者は一般的に高速であり、推奨されます。 リコンサイルは、バインド先のオブジェクトまたはストレージを解放する必要があります。
briefcase リコンサイルで IMoniker::BindToStorage を使用すると、フラット ストレージ (ストリーム) または OLE 定義の構造化ストレージであるストレージにバインドされます。 リコンサイルでフラット ストレージが必要な場合は、IMoniker::BindToStorage を使用して IStream インターフェイスを要求する必要があります。 リコンサイルが構造化ストレージを想定している場合は、 IStorage インターフェイスを要求する必要があります。 どちらの場合も、ストレージへの読み取り専用ダイレクト (非トランザクション) アクセスを要求する必要があります。読み取り/書き込みアクセスが使用できない可能性があります。
通常、最小限の briefcase リコンサイルでは、他のバージョンのストレージを直接見て、2 つのバージョンのオブジェクトをマージして出力バージョンに含めるなど、非常にプリミティブな方法で埋め込みオブジェクトを処理します。
イニシエーターは 、GetClassFile 関数によって実装されたロジックのサブセットを使用して適切な briefcase リコンサイルを検索し、特定のファイルの種類を決定し、指定されたファイルの種類に関連付けられているリコンサイルャー クラスのレジストリを検索します。 他のシェル コンポーネントと同様に、Briefcase は、ファイル名拡張子によってのみファイルの種類を決定します。 ファイルのリコンサイルを呼び出すには、ファイルの拡張子に、Briefcase 用に登録済みのファイルの種類が必要です。 リコンサイルをインストールするときは、次のフォームのレジストリ エントリを設定する必要があります。
CLSID
{the file CLSID}
Roles
Reconciler
(Default) = {the reconciler-classid}
クラスは高速読み込みであり、_MULTIPLEUSE指定する必要があります。また、調整インターフェイスにマーシャラーが指定されていない限り、ローカル サーバー (.exe ファイルに実装されている) ではなく、インプロセス サーバー (DLL に含まれる) である必要があります。
調整でのユーザー操作
briefcase リコンサイルは、ユーザーの操作なしで調整を実行する必要があります。 調整が自動化されるほど、プロセスに対するユーザーの認識が向上します。
場合によっては、ユーザーの介入が重要になる場合があります。 たとえば、ドキュメント システムでは、マージされたバージョンのドキュメントを受け入れる前にユーザーが変更を確認する必要がある場合や、行われた変更を説明するユーザーからのコメントが必要な場合があります。 このような場合、イニシエーターは、ユーザーに対してクエリを実行し、ユーザーの指示を実行する役割を担います。
また、2 つのバージョンが互換性のない方法で編集されている場合など、ユーザーの介入が必要になる場合があります。 このような場合、イニシエーターまたは briefcase リコンサイルは、競合を解決する方法をユーザーに照会する必要があります。 一般に、何らかのユーザー操作を期待せずに調整を完了することにイニシエーターが依存することはできません。 一方、リコンサイザーには、競合を解決するためにユーザーと対話するか、イニシエーターに要求するオプションがあります。
埋め込みオブジェクトの調整
ドキュメントを調整するときに、調整できない型の埋め込みオブジェクトを検出すると、ブリーフケースリコンサイル自体がイニシエーターになる可能性があります。 この場合、リコンサイザーは、各埋め込みオブジェクトを再帰的に調整し、イニシエーターのすべての責任を引き受ける必要があります。
再帰を実行するために、briefcase リコンサイルは、適切なインターフェイスのオブジェクトとクエリを読み込みます。 オブジェクトのハンドラーは、 インターフェイスをサポートしている必要があります。 インターフェイスのいずれかのメソッドがOLE_E_NOTRUNNING値を返す場合、リコンサイルは、操作を実行するために オブジェクトを実行する必要があります。 埋め込みオブジェクトのコードは常に使用できるわけではないため、リコンサイルは、この条件のソリューションを提供する必要があります。 たとえば、リコンサイザーには、リコンサイルされたバージョンに埋め込みオブジェクトの古いバージョンと新しいバージョンの両方が含まれる場合があります。 リコンサイルは、リンク間で調整を試みてはなりません。
イニシエーターは、マージされるドキュメント バージョンを格納します。 多くの場合、イニシエーターは各バージョンのストレージにアクセスでき、同様のストレージを使用して調整の結果を保存します。 ただし、イニシエーターにメモリ内オブジェクトがあり、永続的なバージョンが使用できない場合があります。 この状況は、開いている埋め込みオブジェクトを含むドキュメントを保存する前に調整する必要がある場合に発生する可能性があります。 このような場合、イニシエーターは調整の結果をメモリ内のバージョンに保存します。
イニシエーターは IPersistStorage インターフェイスを使用して、マージされたバージョンをバインド (読み込み) します。 初期バージョンが既に作成されている場合、イニシエーターは IPersistStorage::Load メソッドを使用し、初期バージョンに IPersistStorage::InitNew メソッドを使用します。 マージされたバージョンが読み込まれると、イニシエーターは QueryInterface を 使用して IReconcilableObject インターフェイスのアドレスを取得します。 このインターフェイスにより、イニシエーターは既存の残基のストレージにアクセスでき、新しい残基のストレージを作成する方法が提供されます。 次に、イニシエーターはインターフェイスに調整を実行するように指示します。 イニシエーターは、実際には IPersistStorage の前に IPersistFile インターフェイスを照会します。 リコンサイルモジュールが IPersistFile をサポートしている場合、イニシエーターは IPersistStorage メソッドではなく IPersistFile を使用してレプリカを操作します。 これにより、複合ドキュメントとして保存されていないファイルの調整が可能になります。
調整が完了すると、イニシエーターは IPersistStorage または IPersistFile インターフェイスを使用してマージされたバージョン を 保存できます。 調整中、ブリーフケースリコンサイルは必要に応じて残渣を作成し、永続ビットをストレージに書き込みます。 マージされたバージョンがストリームの場合、IPersistStorage::Load に渡される IStorage インターフェイスには、ストレージ状態が STATEBITS_FLAT に設定された "Contents" という名前のストリームが含まれます。 (状態ビットは、 IStorage::Stat メソッドを使用して設定できます)。マージ後、イニシエーターは適切な方法でデータを書き込むことでマージされたバージョンを保存します。 ストレージに合わせてSTATEBITS_FLATが設定されていることを確認する必要があります。
残 基
イニシエーターは、IReconcilableObject::Reconcile メソッドを呼び出すときに pstgNewResidues パラメーターを有効なアドレスに設定することで、残渣が必要かどうかを示します。 リコンサイル機能が残基の作成をサポートしていない場合は、 dwFlags パラメーターで RECONCILEF_NORESIDUESOK 値が指定されていない限り、REC_E_NORESIDUES値を直ちに返す必要があります。
briefcase リコンサイルサーは、新しいストレージ要素を作成し、 pstgNewResidues が指す配列にコピーすることで、イニシエーターに残渣を返します。 構造化保存残渣の場合、リコンサイルサは IStorage インターフェイスをコピーし、フラットな保存残渣の場合は、STATEBITS_FLAT フラグが設定された IStream または IStorage インターフェイスをコピーします。 リコンサイルサーは IStorage を使用して必要なストレージを作成し、 IStorage::CreateStream を使用してストリームである残渣のフラット ストレージを作成し、 IStorage::CreateStorage を使用して構造化ストレージを作成します。
イニシエーターは、IStorage 名前空間の予約されていない部分に要素が含まれないように pstgNewResidues を準備します。 ブリーフケースリコンサイラーは、最初のバージョンの順序に対応する名前の要素に各残基を配置します。 たとえば、最初の残基は "1" に、2 番目の残基は "2" に含まれています。 調整されたオブジェクト自体が残基を生成する場合は、"0" という名前の要素にあります。
ブリーフケース調整ツールは、新しく作成された各要素を個別にコミットし、イニシエーターが情報にアクセスできるようにします。 ただし、リコンサイル機能は pstgNewResidues 自体を コミットしません。 イニシエーターは、これをコミットするか、それ以外の場合は破棄する責任があります。
Briefcase Reconciler リファレンス
このセクションには、調整インターフェイスに関する情報が含まれています。 エラーを処理する場合、メソッドは、可能な戻り値として明示的に定義されているエラー値のみを返すことができます。 さらに、 メソッドは、エラーから戻る前に、アドレスがパラメーターとして渡されるすべての変数を NULL に設定する必要があります。
Briefcase リコンサイルサーのインターフェイスとメソッド