ISyncChangeBatchBase2::SerializeWithOptions

  • [アーティクル]

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

構文

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

パラメーター

項目

定義

targetFormatVersion

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

dwFlags

[in] 予約済み。0 を指定する必要があります。

pbBuffer

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

pdwSerializedSize

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

戻り値

  • S_OK

  • E_INVALIDARG (dwFlags が 0 でない場合、または targetFormatVersion によって指定されたバージョンと変更バッチ オブジェクトのデータに互換性がない場合)

  • E_OUTOFMEMORY

  • E_POINTER

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

  • SYNC_E_INVALID_OPERATION (開始されて終了していないグループが変更バッチに含まれている場合)

  • 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 を指定すると、E_INVALIDARG または SYNC_E_INVALID_OPERATION が返されます。

注意

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

シリアル化形式

pbBuffer に含まれるシリアル化された変更バッチは、埋め込みなしのコンパクトな形式で、ビッグ エンディアンのバイト順に格納されています。シリアル化された変更バッチには、以下の要素が以下に示す順序で含まれます。

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

    データ型

    バイト数

    説明

    ULONGLONG

    8

    変更バッチのシリアル化形式のバージョンです。この値は、targetFormatVersion が SYNC_SERIALIZATION_VERSION_V1 の場合は 3、targetFormatVersion が SYNC_SERIALIZATION_VERSION_V2 の場合は 4、targetFormatVersion が SYNC_SERIALIZATION_VERSION_V3 の場合は 5 になります。

  2. 1 つのフィルター情報セクション (targetFormatVersion が SYNC_SERIALIZATION_VERSION_V2 で、フィルター情報が変更バッチで示される場合)。フィルター情報セクションには、次の要素が含まれます。

    データ型

    バイト数

    説明

    ULONG

    4

    フィルター情報セクションの長さ (バイト数) です。

    残りのフィルター情報セクションは、ISyncFilterInfo::Serialize で示される形式になります。

  3. 1 つの同期先ナレッジ セクション。同期先ナレッジ セクションには、次の要素が含まれます。

    データ型

    バイト数

    説明

    ULONG

    4

    同期先ナレッジ セクションの長さ (バイト数) です。この長さには 0 を指定できます。この場合、同期先ナレッジは存在しないということになります。

    バイト シーケンス

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

    targetFormatVersion が SYNC_SERIALIZATION_VERSION_V1 の場合、同期先ナレッジは ISyncKnowledge::Serialize によって示される形式になります。それ以外の場合、同期先ナレッジは ISyncKnowledge2::SerializeWithOptions によって示される形式になります。シリアル化された同期先ナレッジには、常に、シリアル化されたレプリカ キー マップが含まれます。

  4. 1 つの同期元の忘れられたナレッジ セクション。同期元の忘れられたナレッジ セクションには、次の要素が含まれます。

    データ型

    バイト数

    説明

    ULONG

    4

    同期元の忘れられたナレッジ セクションの長さ (バイト数) です。この長さには 0 を指定できます。この場合、同期元の忘れられたナレッジは存在しないということになります。

    バイト シーケンス

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

    targetFormatVersion が SYNC_SERIALIZATION_VERSION_V1 の場合、同期元の忘れられたナレッジは ISyncKnowledge::Serialize によって示される形式になります。それ以外の場合、同期元の忘れられたナレッジは ISyncKnowledge2::SerializeWithOptions によって示される形式になります。シリアル化された同期元の忘れられたナレッジには、常に、シリアル化されたレプリカ キー マップが含まれます。

  5. 同期元の 1 つのフィルター キー マップ セクション (targetFormatVersion が SYNC_SERIALIZATION_VERSION_V3 で、同期元のフィルター キー マップ情報が存在する場合)。同期元のフィルター キー マップ セクションには、次の要素が含まれます。

    データ型

    バイト数

    説明

    ULONG

    4

    同期元のフィルター キー マップ セクションの長さ (バイト数) です。この長さには 0 を指定できます。この場合、同期元のフィルター キー マップは存在しないことになります。

    USHORT

    2

    フィルター キー マップのシリアル化形式のバージョンです。この値は SYNC_SERIALIZATION_VERSION_V3 です。

    ULONG

    4

    フィルター キー マップのフィルター数です。

    フィルター キー マップの各フィルターには、次の要素が含まれます。

    データ型

    バイト数

    説明

    ULONG

    4

    フィルターの長さ (バイト数) です。

    バイト シーケンス

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

    ISyncFilter::Serialize メソッドによってストリームに書き込まれた、シリアル化されたフィルター データです。

  6. 1 つの関連付けられているナレッジ セクション。関連付けられているナレッジ セクションには、次の要素が含まれます。

    データ型

    バイト数

    説明

    ULONG

    4

    シリアル化されたデータに含まれる、関連付けられているナレッジ オブジェクトの数です。この数には 0 を指定できます。この場合、関連付けられているナレッジは存在しないということになります。

    関連付けられているナレッジごとに、次の要素が含まれます。

    データ型

    バイト数

    説明

    ULONG

    4

    関連付けられているナレッジの長さ (バイト数) です。

    バイト シーケンス

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

    targetFormatVersion が SYNC_SERIALIZATION_VERSION_V1 の場合、関連付けられているナレッジは ISyncKnowledge::Serialize によって示される形式になります。それ以外の場合、関連付けられているナレッジは ISyncKnowledge2::SerializeWithOptions によって示される形式になります。シリアル化された、関連付けられているナレッジには、常に、シリアル化されたレプリカ キー マップが含まれます。

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

    データ型

    バイト数

    説明

    ULONG

    4

    シリアル化されたデータに含まれる変更オブジェクトの数です。この数には 0 を指定できます。この場合、変更は存在しないということになります。

    各変更には、次の要素が含まれます。

    データ型

    バイト数

    説明

    ULONG

    4

    変更データの長さ (バイト数) です。

    ULONGLONG

    8

    変更オブジェクトのシリアル化形式の署名です。この値は、targetFormatVersion が SYNC_SERIALIZATION_VERSION_V1 または SYNC_SERIALIZATION_VERSION_V2 の場合は 5、targetFormatVersion が SYNC_SERIALIZATION_VERSION_V3 の場合は 6 になります。

    レプリカ ID が固定長の場合は、次のとおりです。

    データ型

    バイト数

    説明

    バイト シーケンス

    レプリカ ID の形式で指定された長さ

    固定長のレプリカ ID です。

    レプリカ ID が可変長の場合は、次のとおりです。

    データ型

    バイト数

    説明

    USHORT

    2

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

    バイト シーケンス

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

    可変長のレプリカ ID です。

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

    データ型

    バイト数

    説明

    ULONG

    4

    この変更を加えたレプリカを識別するレプリカ キーです。

    ULONGLONG

    8

    この変更を加えたレプリカのティック数です。

    ULONG

    4

    予約済み。この値は無視できます。

    ULONGLONG

    8

    予約済み。この値は無視できます。

    ULONG

    4

    この項目を作成したレプリカを識別するレプリカ キーです。

    ULONGLONG

    8

    この項目を作成したレプリカのティック数です。

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

    データ型

    バイト数

    説明

    バイト シーケンス

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

    固定長の項目 ID です。

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

    データ型

    バイト数

    説明

    USHORT

    2

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

    バイト シーケンス

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

    可変長の項目 ID です。

    targetFormatVersion が SYNC_SERIALIZATION_VERSION_V3 以上の場合、各変更には次の追加要素が含まれます。

    データ型

    バイト数

    説明

    BOOL

    1

    優先される ID がシリアル化されたデータに存在するかどうかを示します。値 0 は、優先される ID が存在しないことを示します。値 1 は、優先される ID が存在することを示します。

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

    データ型

    バイト数

    説明

    バイト シーケンス

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

    固定長の優先される ID です。

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

    データ型

    バイト数

    説明

    USHORT

    2

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

    バイト シーケンス

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

    可変長の優先される ID です。

    すべての変更には、次の追加要素が含まれます。

    データ型

    バイト数

    説明

    ULONG

    4

    変更に関連付けられたフラグです。これは、SYNC_CHANGE_FLAG フラグの組み合わせです。

    ULONG

    4

    変更の作業見積もりです。

    USHORT

    2

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

    BYTE

    1

    この変更に関連付けられている学習したナレッジが、この項目に射影されるかどうかを示します。値 0 は、学習したナレッジが射影されないことを示します。値 1 は、学習したナレッジが射影されることを示します。

    ULONG

    4

    このシリアル化されたデータに含まれている、関連付けられているナレッジの一覧へのインデックスです。この値には 0 を指定できます。これは、関連付けられているナレッジが、この項目に関連付けられていないことを示します。

    ULONG

    4

    この変更に含まれている変更単位の数です。この値には 0 を指定できます。この場合、変更単位は存在しないということになります。

    変更には、変更単位の一覧が含まれます。この一覧の変更単位の数は、上記の ULONG に格納された値と一致します。

    各変更単位には、次の要素が含まれます。

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

    データ型

    バイト数

    説明

    バイト シーケンス

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

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

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

    データ型

    バイト数

    説明

    USHORT

    2

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

    バイト シーケンス

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

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

    各変更単位には、次の追加要素が含まれます。

    データ型

    バイト数

    説明

    ULONG

    4

    この変更を加えたレプリカを識別するレプリカ キーです。

    ULONGLONG

    8

    この変更を加えたレプリカのティック数です。

    ULONG

    4

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

    ULONGLONG

    8

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

  8. 1 つの復旧同期セクション。復旧同期セクションには、次の要素が含まれます。

    データ型

    バイト数

    説明

    ULONG

    4

    復旧同期セクションの長さ (バイト数) です。この値が 0 の場合、復旧同期セクションは存在しないということになります。

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

    データ型

    バイト数

    説明

    バイト シーケンス

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

    変更バッチが復旧同期に含まれている場合に、この変更バッチ内の変更の下限を表す固定長の項目 ID です。

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

    データ型

    バイト数

    説明

    USHORT

    2

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

    バイト シーケンス

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

    変更バッチが復旧同期に含まれている場合に、この変更バッチ内の変更の下限を表す可変長の項目 ID です。

  9. 1 つの作業見積もりセクション。作業見積もりセクションには、次の要素が含まれます。

    データ型

    バイト数

    説明

    ULONG

    4

    同期セッションの作業見積もりです。

    ULONG

    4

    この変更バッチの作業見積もりです。

  10. 1 つのフラグ セクション。フラグ セクションには、次の要素が含まれます。

    データ型

    バイト数

    説明

    BYTE

    1

    この変更バッチが、同期元プロバイダーから送信された最後の変更バッチであるかどうかを示します。値 0 は、これが最後の変更バッチではないことを示します。値 1 は、これが最後の変更バッチであることを示します。

    BYTE

    1

    この変更バッチが復旧同期に含まれているかどうかを示します。値 0 は、この変更バッチが復旧同期に含まれていないことを示します。値 1 は、この変更バッチが復旧同期に含まれていることを示します。

    BYTE

    1

    この変更バッチがフィルター選択されているかどうかを示します。値 0 は、この変更バッチがフィルター選択されていないことを示します。値 1 は、この変更バッチがフィルター選択されていることを示します。

関連項目

その他の技術情報

ISyncChangeBatchBase2 インターフェイス