ISyncKnowledge2::SerializeWithOptions

  • [アーティクル]

指定されたバージョンとシリアル化のオプションに基づいて、ナレッジ オブジェクトのデータをバイト配列にシリアル化します。

HRESULT SerializeWithOptions(
  SYNC_SERIALIZATION_VERSION targetFormatVersion,
  DWORD dwFlags,
  BYTE* pBuffer,
  DWORD* pdwSerializedSize);

パラメーター

項目

定義

targetFormatVersion

[in] シリアル化されたナレッジはこのバージョンと互換性があります。

dwFlags

[in] オブジェクトをシリアル化する方法に関する追加情報を指定するオプションです。0、または SYNC_SERIALIZE フラグで指定された値の組み合わせを指定する必要があります。0 を指定した場合、レプリカ キー マップは、シリアル化されたナレッジ データの一部として含まれません。

pBuffer

[in, out, unique, size_is(*pdwSerializedSize)] シリアル化されたナレッジ オブジェクトのデータはこのバッファーにシリアル化されます。

pdwSerializedSize

[in, out] pBuffer のバイト数を指定します。書き込まれたバイト数を返します。pBuffer が小さすぎる場合は、ナレッジ データをシリアル化するために必要なバイト数を返します。

戻り値

  • S_OK

  • E_POINTER

  • HRESULT_FROM_WIN32(ERROR_MORE_DATA) (pBuffer が小さすぎる場合。この場合、必要なバイト数が pdwSerializedSize で返されます。)

  • SYNC_E_INVALID_VERSION (targetFormatVersion の値がオブジェクトのバージョンの値より大きい場合、または targetFormatVersion と互換性のない要素がオブジェクトに含まれている場合)

解説

targetFormatVersion の値によって、シリアル化されたナレッジ データの形式が決まります。SYNC_SERIALIZATION_VERSION_V1 を指定した場合、シリアル化された形式は Sync Framework 1.0 以降のコンポーネントと互換性があります。SYNC_SERIALIZATION_VERSION_V2 を指定した場合、シリアル化された形式は Sync Framework 2.0 のコンポーネントと互換性があります。Sync Framework 1.0 と互換性のない要素がナレッジ オブジェクトに含まれている場合に SYNC_SERIALIZATION_VERSION_V2 を指定すると、SYNC_E_INVALID_VERSION が返されます。たとえば、ISyncKnowledge2::ProjectOntoColumnSet によって返されるナレッジは、Sync Framework 2.0 で導入された要素を含んでいるため、targetFormatVersion に SYNC_SERIALIZATION_VERSION_V1 が指定されているとシリアル化できません。

注意

Sync Framework 1.0 形式へのシリアル化は、Sync Framework 2.0 形式へのシリアル化に比べて効率が劣ります。Sync Framework 1.0 形式のニーズが特にない限り、Sync Framework 2.0 形式を使用してください。

IProviderSyncServices::DeserializeSyncKnowledge を使用してナレッジ オブジェクトのシリアル化を解除するには、適切な IReplicaKeyMap インターフェイス オブジェクトが必要です。flags に SYNC_SERIALIZE_REPLICA_KEY_MAP が指定されている場合は、IReplicaKeyMap オブジェクトがナレッジ データと共にシリアル化されます。このフラグが指定されていない場合は、ナレッジ オブジェクトのシリアル化を解除できるように、別の方法で IReplicaKeyMap データを格納する必要があります。

シリアル化形式

pBuffer に含まれるシリアル化されたナレッジは、埋め込みなしのコンパクトな形式で、ビッグ エンディアンのバイト順に格納されています。

targetFormatVersion が SYNC_SERIALIZATION_VERSION_V1 の場合、ナレッジは、「ISyncKnowledge::Serialize」で説明されている形式に従ってシリアル化されます。それ以外の場合、シリアル化されたナレッジには、以下の要素が以下に示す順序で格納されます。

  1. 1 つのヘッダー セクション。ヘッダー セクションには、次の要素が含まれます。

    データ型 バイト数 説明

    ULONG

    4

    シリアル化形式のバージョンです。これは、targetFormatVersion に格納される値で、SYNC_SERIALIZATION_VERSION 列挙体の有効な値である必要があります。

    ULONG

    4

    予約済み。この値は常に 0 です。

    ULONG

    4

    シリアル化されたナレッジのサポートされる最小バージョンです。

    ULONG

    4

    予約済み。この値は常に 0 です。

  2. dwFlags に SYNC_SERIALIZE_REPLICA_KEY_MAP が含まれる場合は 1 つのレプリカ キー マップ セクション。それ以外の場合、レプリカ キー マップ セクションは存在しません。レプリカ キー マップ セクションの形式は、IReplicaKeyMap::Serialize で定義されます。

  3. 次のセクションのセットを示す署名。

    データ型 バイト数 説明

    ULONG

    4

    セクションの署名です。この値は常に 24 です。

  4. 1 つの ID 形式スキーマ セクション。ID 形式スキーマ セクションには、次の要素が含まれます。

    データ型 バイト数 説明

    BOOL

    1

    ナレッジに含まれるレプリカ ID が固定長か可変長かを示します。この値は、ID が固定長の場合に 0、可変長の場合に 1 になります。

    USHORT

    2

    固定長 ID の場合はレプリカ ID の長さ (バイト数)、可変長 ID の場合は ID の最大長です。

    BOOL

    1

    ナレッジに含まれる項目 ID が固定長か可変長かを示します。この値は、ID が固定長の場合に 0、可変長の場合に 1 になります。

    USHORT

    2

    固定長 ID の場合は項目 ID の長さ (バイト数)、可変長 ID の場合は ID の最大長です。

    BOOL

    1

    ナレッジに含まれる変更単位 ID が固定長か可変長かを示します。この値は、ID が固定長の場合に 0、可変長の場合に 1 になります。

    USHORT

    2

    固定長 ID の場合は変更単位 ID の長さ (バイト数)、可変長 ID の場合は ID の最大長です。

  5. 1 つのクロック ベクター テーブル セクション。クロック ベクター テーブル セクションには、次の要素が含まれます。

    データ型 バイト数 説明

    ULONG

    4

    クロック ベクター テーブルの署名です。この値は常に 21 です。

    ULONG

    4

    クロック ベクター テーブルに含まれるクロック ベクターの数です。

  6. クロック ベクター テーブルには、クロック ベクターの一覧が含まれ、この一覧のクロック ベクターの数は、上記の ULONG に指定された値と一致します。各クロック ベクターには、次の要素が含まれます。

    データ型 バイト数 説明

    ULONG

    4

    クロック ベクターの署名です。この値は、クロック ベクターに FeedSync フィード項目が含まれていない場合に 1、それ以外の場合 (クロック ベクターに FeedSync フィード項目が含まれている場合) に 9 になります。

    ULONG

    4

    このクロック ベクターに含まれるクロック ベクター要素の数です。

    クロック ベクターに FeedSync フィード項目が含まれている場合は、次のセクションがシリアル化されたナレッジに存在します。それ以外の場合、次のセクションは存在しません。

    データ型 バイト数 説明

    ULONG

    4

    このナレッジに関連付けられている FeedSync フィードにこれまでに適用された更新の数です。この値は、FeedSync フィードの updates 属性に対応します。

    BYTE

    1

    FeedSync フィードが競合を追跡するかどうかを示します。この値は、FeedSync フィードの noconflicts 属性に対応します。この値は、noconflicts 属性が設定されていない場合は 0、それ以外の場合は 1 になります。

    残りのクロック ベクター セクションには、クロック ベクター要素の一覧が含まれ、この一覧の要素の数は、上記のクロック ベクター セクションで指定した値と一致します。

    各クロック ベクター要素には、次の要素が含まれます。

    データ型 バイト数 説明

    ULONG

    4

    レプリカ キーです。

    ULONGLONG

    8

    ティック数です。

    ナレッジが FeedSync フィードに関連付けられている場合、各クロック ベクター要素には次の追加要素が含まれます。

    データ型 バイト数 説明

    ULONG

    4

    FeedSync フィードの when 値の日付部分です。

    ULONG

    4

    FeedSync フィードの when 値の時刻部分です。

    BYTE

    1

    FeedSync フィードに関連付けられているフラグです。

  7. 1 つの範囲セット セクション。範囲セット セクションには、次の要素が含まれます。

    データ型 バイト数 説明

    ULONG

    4

    範囲セット セクションの署名です。この値は常に 23 です。

    ULONG

    4

    このセクションに含まれている範囲セットの数です。

    範囲セット セクションには、範囲セットの一覧が含まれ、この一覧の範囲セットの数は、上記の ULONG に指定された値と一致します。最初の範囲セットは、スコープの範囲セットです。

    各範囲セットには、次の要素が含まれます。

    データ型 バイト数 説明

    ULONG

    4

    範囲セットの署名です。この値は常に 22 です。

    ULONG

    4

    この範囲セットに含まれている範囲の数です。

    範囲セットの各範囲には、次の要素が含まれます。

    項目 ID が固定長の場合は、次のとおりです。

    データ型 バイト数 説明

    バイト シーケンス

    項目 ID 形式で指定された長さ

    範囲の先頭にある固定長項目 ID です。

    項目 ID が可変長の場合は、次のとおりです。

    データ型 バイト数 説明

    USHORT

    2

    可変長 ID の長さ (バイト数) です。この長さには、長さを示す USHORT の 2 バイトに加えて、実際の ID を示すバイト列が含まれます。

    バイト シーケンス

    上記の USHORT で指定された長さ

    範囲の先頭にある可変長項目 ID です。

    各範囲には、次の追加要素が含まれます。

    データ型 バイト数 説明

    ULONG

    4

    このシリアル化されたデータに含まれているクロック ベクター テーブルへのインデックスです。

  8. 1 つの列セット セクション。列セット セクションには、次の要素が含まれます。

    データ型 バイト数 説明

    ULONG

    4

    このセクションに含まれている列の数です。

    列セット セクションの各列には、次の要素が含まれます。

    変更単位 ID が固定長の場合は、次のとおりです。

    データ型 バイト数 説明

    バイト シーケンス

    変更単位 ID 形式で指定された長さ

    固定長の変更単位 ID です。

    変更単位 ID が可変長の場合は、次のとおりです。

    データ型 バイト数 説明

    USHORT

    2

    可変長 ID の長さ (バイト数) です。この長さには、長さを示す USHORT の 2 バイトに加えて、実際の ID を示すバイト列が含まれます。

    バイト シーケンス

    上記の USHORT で指定された長さ

    可変長の変更単位 ID です。

    列セット セクションの各列には、次の追加要素が含まれます。

    データ型 バイト数 説明

    ULONG

    4

    このシリアル化されたデータに含まれている範囲セット セクションへのインデックスです。

  9. targetFormatVersion が SYNC_SERIALIZATION_VERSION_V3 以上の場合、シリアル化されたデータには 1 つのマーカー セット セクションが含まれます。マーカー セット セクションには、次の要素が含まれます。

    データ型 バイト数 説明

    ULONG

    4

    マーカー セット セクションの署名です。この値は常に 25 です。

    BOOL

    1

    このセクションに表示される項目にすべての変更単位が含まれているか、すべての変更単位を必要としているかを示します。この値は、変更単位が含まれている場合に 0、変更単位が必要な場合に 1 になります。含めることができるのは、これらのマーカー タイプの 1 つだけです。

    ULONG

    4

    このセクションに含まれている項目 ID の数です。

    マーカー セット セクションには、項目 ID の一覧が含まれ、この一覧の ID の数は上記の ULONG に格納されている値と一致します。

    各項目 ID には、次の要素が含まれます。

    項目 ID が固定長の場合は、次のとおりです。

    データ型 バイト数 説明

    バイト シーケンス

    項目 ID 形式で指定された長さ

    固定長の項目 ID です。

    項目 ID が可変長の場合は、次のとおりです。

    データ型 バイト数 説明

    USHORT

    2

    可変長 ID の長さ (バイト数) です。この長さには、長さを示す USHORT の 2 バイトに加えて、実際の ID を示すバイト列が含まれます。

    バイト シーケンス

    上記の USHORT で指定された長さ

    可変長の項目 ID です。

参照

リファレンス

ISyncKnowledge2 インターフェイス