フレキシブル ID
フレキシブル ID は、レプリカ、項目、または変更単位を識別する目的で使用されます。Sync Framework では、次の種類のフレキシブル ID がサポートされます。
固定長 ID
固定長 ID は、いつ使用しても常に同じ長さになります。長さは、ID 形式スキーマで指定されます。
可変長 ID
可変長 ID は、使用するたびに長さが変わる場合があります。最大長は、ID 形式スキーマで指定されます。
マネージ コード : ID は SyncId クラスで表されます。このクラスは、ID の他に、その ID が可変長であるかどうかを示す値を保持します。
アンマネージ コード : ID はバイト配列として表されます。可変長 ID は SYNC_ID 構造体で表されます。この構造体は、ID の長さ、およびバイト配列で表現された ID を保持します。
ID スキーマ
ID の形式はスキーマで定義されます。スキーマでは、システム内の各 ID について次の情報が指定されます。
ID が固定長か可変長か。
サイズ (ID が固定長である場合) または最大サイズ (ID が可変長である場合)。
マネージ コード : ID 形式スキーマは、SyncIdFormatGroup クラスを使用して指定されます。
アンマネージ コード : ID 形式スキーマは、ID_PARAMETERS 構造体を使用して指定されます。
Sync Framework の各種メソッドには、このスキーマを指定する必要があります。このスキーマを利用することによって、すべてのオブジェクトで確実に同じ ID スキーマ情報を使用することができます。
同期セッションでは、両方のプロバイダーに対して、対応するスキーマが照会されます。スキーマを比較することにより、両方のプロバイダーで同じスキーマが使用されていることが確認されます。この検証に失敗した場合、セッションは作成されません。
マネージ コード : プロバイダーのスキーマは、IdFormats プロパティを使用して取得されます。
アンマネージ コード : プロバイダーのスキーマは、ISyncProvider::GetIdParameters メソッドを使用して取得されます。
注意
Sync Framework のメソッドに渡される ID の形式は、ID 形式スキーマに指定された形式と一致している必要があります。一致しない場合、メソッドでエラーが発生します。
グローバル ID の推奨される形式
同期スコープのすべての項目には、それぞれのグローバル ID が必要です。また、この ID は、同期コミュニティ全体を通じて一意である必要があります。グローバル ID はフレキシブル ID であるため、任意の形式を使用できます。ただし、メタデータは、順序付けられた一連の ID を単一の範囲として表すことができるため、ID を順序付けられたグループとして列挙することで、メタデータをコンパクトにすることができます。また、範囲を使用することにより、メタデータのメンテナンスを効率的に行うことができます。そのため、ID の順序がそのまま列挙に適した順序となるようにすると効果的です。グローバル ID の形式については、マネージの SyncGlobalId クラスやアンマネージの SYNC_GID 構造体のように、8 バイトのプレフィックスを持つ 16 バイトの GUID を推奨します。
階層データに関する注意事項
同期中の項目が階層構造になっているような場合は、クロック タイムなどの単調に増加する数字を ID プレフィックスに配置すると便利なときがあります。通常、親は子よりも先に作成されるため、列挙の順序において親は子よりも先に出現することになります。こうすることで、プロバイダーは、適用順序が適切でない項目を、より簡単に解決できるようになります。
階層データにグローバル ID を割り当てる際の 1 つのアプローチとして、次のような方法が考えられます。
レプリカ内のすべての項目を一意にインデックス化できるだけの十分な大きさを持つカウンターを作成します。
スコープのルートを起点として、深さ、幅の順にシステムをスキャンします。
各項目 (親または子) について、GUID を生成します。
GUID のプレフィックスには、ウォール クロック タイムを使用します。
新たに作成された項目にも、コンテナーまたは入れ子にされた個々の項目に関係なく、これと同じ方法でグローバル ID を割り当てることができます。
アンマネージ コードにおけるメモリ処理
ID はバイト配列へのポインターとして表されます。したがって、固定長の ID では、使用されている ID をバイト ポインターにキャストすることができます。可変長 ID の場合、ID データには、SYNC_ID 構造体と同様、プレフィックスとしてバッファー サイズが指定されている必要があります。
注意
Sync Framework は、呼び出し元によって割り当てられた ID への参照を保持しません。Sync Framework が ID を維持する必要がある場合は、その ID に対して別途メモリを割り当てて、ID を内部的にコピーします。ID に関連するメモリの割り当てと解放は、呼び出し元で行う必要があります。
アンマネージ コードにおける戻り値としての ID
Sync Framework のメソッドからは、次の 2 回の呼び出しプロセスで可変長 ID が返されます。
メソッドを呼び出して、ID のサイズを調べます。
呼び出し元はメモリを割り当てて、再度、関数を呼び出します。このときに、新たに割り当てたバッファーとそのサイズを指定します。
ユーザーは、正確なサイズのバッファーを割り当てるか、最大サイズのバッファーを割り当てることによって、このプロセスを最適化できます。この場合、呼び出し元は、バッファーが正しいサイズであったことを確認するために、返された HRESULT を常に確認する必要がありますが、最初の呼び出しは必要ではありません。
固定長 ID を返すメソッドでは、2 段階のプロセスは使用されません。単に、バッファーのサイズを正確に指定するだけです。固定長 ID を要求する場合、サイズ パラメーターは省略可能です (NULL を指定できます)。サイズを指定した場合、メソッドの動作は可変長 ID のケースと同様です。つまり、指定したサイズが、実際に返される ID よりも小さい場合、他にもデータがあることを示すエラー コードが返され、サイズ変数には、必要なサイズが格納されます。指定されたサイズが、実際に必要なサイズよりも大きかった場合、メソッドは成功し、必要なサイズが返されます。
範囲
順序付けられた ID のブロックを "範囲" と呼ぶことがあります。範囲は、ID の下限と上限を使用して定義されます (両端を含みます)。
マネージ コード : 特定の範囲に作用するメソッドに対し、その範囲の両端を直接指定します。
アンマネージ コード : 範囲は、SYNC_RANGE 構造体を使用して表されます。
参照
リファレンス
ID_PARAMETERS 構造体
ID_PARAMETER_PAIR 構造体
SYNC_ID 構造体
SYNC_RANGE 構造体
SyncIdFormatGroup
SyncIdFormat
SyncId