通过

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。

  • 当 dwFlags 不为 0 时，或者 targetFormatVersion 指定的版本与变更批对象数据不兼容时，为 E_INVALIDARG。

  • E_OUTOFMEMORY。

  • E_POINTER。

  • 如果 pBuffer 太小，则返回值为 HRESULT_FROM_WIN32(ERROR_MORE_DATA)。在此情况下，将在 pdwSerializedSize 中返回必需的字节数。

  • 当变更批包含已经开始但未结束的组时，为 SYNC_E_INVALID_OPERATION。

  • 当 targetFormatVersion 的值高于该对象的版本时，或者该对象包含与 targetFormatVersion 不兼容的元素时，为 SYNC_E_INVALID_VERSION。

备注

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 中的序列化变更批以压缩形式（没有填充）并按 Big-Endian 字节顺序存储。序列化变更批按如下顺序包含以下元素。

  1. 一个标头部分。该标头部分包含以下元素。

    数据类型 以字节为单位的长度 说明

    ULONGLONG

    8

    变更批的序列化格式的版本。当 targetFormatVersion 为 SYNC_SERIALIZATION_VERSION_V1 时，此值是 3；当 targetFormatVersion 为 SYNC_SERIALIZATION_VERSION_V2 时，此值是 4；当 targetFormatVersion 为 SYNC_SERIALIZATION_VERSION_V3 时，此值是 5。

  2. 一个筛选器信息部分（当 targetFormatVersion 为 SYNC_SERIALIZATION_VERSION_V2 并且变更批中包含筛选器信息时）。该筛选器信息部分包含以下元素。

    数据类型 以字节为单位的长度 说明

    ULONG

    4

    筛选器信息部分的长度（以字节为单位）。

    筛选器信息部分的剩余内容采用在 ISyncFilterInfo::Serialize 中介绍的格式。

  3. 一个目标知识部分。该目标知识部分包含以下元素。

    数据类型 以字节为单位的长度 说明

    ULONG

    4

    目标知识部分的长度（以字节为单位）。此长度可以为 0，在这种情况下，不包含任何目标知识。

    字节序列

    上一个 ULONG 中指定的长度。

    当 targetFormatVersion 为 SYNC_SERIALIZATION_VERSION_V1 时，目标知识将采用 ISyncKnowledge::Serialize 描述的格式。否则，目标知识将采用 ISyncKnowledge2::SerializeWithOptions 描述的格式。序列化的目标知识始终包含序列化副本键映射。

  4. 一个源遗忘知识部分。该源遗忘知识部分包含以下元素。

    数据类型 以字节为单位的长度 说明

    ULONG

    4

    源遗忘知识部分的长度（以字节为单位）。此长度可以为 0，在这种情况下，不包含任何源遗忘知识。

    字节序列

    上一个 ULONG 中指定的长度。

    当 targetFormatVersion 为 SYNC_SERIALIZATION_VERSION_V1 时，源遗忘知识将采用 ISyncKnowledge::Serialize 描述的格式。否则，源遗忘知识将采用 ISyncKnowledge2::SerializeWithOptions 描述的格式。序列化的源遗忘知识始终包含序列化副本键映射。

  5. 一个源筛选器键映射部分（当 targetFormatVersion 为 SYNC_SERIALIZATION_VERSION_V3，且源筛选器键映射信息存在时）。源筛选器键映射部分包含以下元素。

    数据类型 以字节为单位的长度 说明

    ULONG

    4

    筛选器键映射部分的长度（以字节为单位）。此长度可以为 0，在这种情况下，不包含任何筛选器键映射。

    USHORT

    2

    筛选器键映射的序列化格式的版本。此值为 SYNC_SERIALIZATION_VERSION_V3。

    ULONG

    4

    筛选器键映射中的筛选器数。

    筛选器键映射中的每个筛选器都包含以下元素。

    数据类型 以字节为单位的长度 说明

    ULONG

    4

    筛选器的长度（以字节为单位）。

    字节序列

    上一个 ULONG 中指定的长度。

    通过 ISyncFilter::Serialize 方法写入流中的序列化筛选器数据。

  6. 一个生成知识部分。该生成知识部分包含以下元素。

    数据类型 以字节为单位的长度 说明

    ULONG

    4

    包含在序列化数据中的生成知识对象的数量。此数量可以为 0，在这种情况下，不包含任何生成知识。

    每个生成知识都包含以下元素。

    数据类型 以字节为单位的长度 说明

    ULONG

    4

    生成知识的长度（以字节为单位）。

    字节序列

    上一个 ULONG 中指定的长度。

    当 targetFormatVersion 为 SYNC_SERIALIZATION_VERSION_V1 时，生成知识将采用 ISyncKnowledge::Serialize 描述的格式。否则，生成知识将采用 ISyncKnowledge2::SerializeWithOptions 描述的格式。序列化的生成知识始终包含序列化副本键映射。

  7. 一个变更集部分。该变更集部分包含以下元素。

    数据类型 以字节为单位的长度 说明

    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 的两个字节以及包含实际 ID 的字节。

    字节序列

    上一个 USHORT 中指定的长度。

    可变长度的副本 ID。

    每个变更都包含以下附加元素。

    数据类型 以字节为单位的长度 说明

    ULONG

    4

    标识做出了此变更的副本的副本键。

    ULONGLONG

    8

    做出了此变更的副本的滴答计数。

    ULONG

    4

    保留。可以忽略此值。

    ULONGLONG

    8

    保留。可以忽略此值。

    ULONG

    4

    标识创建了此项的副本的副本键。

    ULONGLONG

    8

    创建了此项的副本的滴答计数。

    当项 ID 为固定长度时。

    数据类型 以字节为单位的长度 说明

    字节序列

    在项 ID 格式中指定的长度。

    固定长度的项 ID。

    或者，当项 ID 为可变长度时。

    数据类型 以字节为单位的长度 说明

    USHORT

    2

    可变长度的 ID 的长度（以字节为单位）。此长度包括包含长度的 USHORT 的两个字节以及包含实际 ID 的字节。

    字节序列

    上一个 USHORT 中指定的长度。

    可变长度的项 ID。

    当 targetFormatVersion 为 SYNC_SERIALIZATION_VERSION_V3 或更高时，每个变更都将包含以下附加元素。

    数据类型 以字节为单位的长度 说明

    BOOL

    1

    指示入选方 ID 是否存在于序列化数据中。值为 0 表示不包含任何入选方 ID。值为 1 表示包含入选方 ID。

    当项 ID 为固定长度时。

    数据类型 以字节为单位的长度 说明

    字节序列

    在项 ID 格式中指定的长度。

    固定长度的入选方 ID。

    或者，当项 ID 为可变长度时。

    数据类型 以字节为单位的长度 说明

    USHORT

    2

    可变长度的 ID 的长度（以字节为单位）。此长度包括包含长度的 USHORT 的两个字节以及包含实际 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 的两个字节以及包含实际 ID 的字节。

    字节序列

    上一个 USHORT 中指定的长度。

    可变长度的变更单位 ID。

    每个变更单位都包含以下附加元素。

    数据类型 以字节为单位的长度 说明

    ULONG

    4

    标识做出了此变更的副本的副本键。

    ULONGLONG

    8

    做出了此变更的副本的滴答计数。

    ULONG

    4

    保留。此值始终为 0。

    ULONGLONG

    8

    保留。此值始终为 0。

  8. 一个恢复同步部分。该恢复同步部分包含以下元素。

    数据类型 以字节为单位的长度 说明

    ULONG

    4

    恢复同步部分的长度（以字节为单位）。当此值为 0 时，不包含任何恢复同步部分。

    当项 ID 为固定长度时。

    数据类型 以字节为单位的长度 说明

    字节序列

    在项 ID 格式中指定的长度。

    如果变更批是恢复同步的一部分，则为表示此变更批中变更的下限的项 ID，该 ID 的长度是固定的。

    或者，当项 ID 为可变长度时。

    数据类型 以字节为单位的长度 说明

    USHORT

    2

    可变长度的 ID 的长度（以字节为单位）。此长度包括包含长度的 USHORT 的两个字节以及包含实际 ID 的字节。

    字节序列

    上一个 USHORT 中指定的长度。

    如果变更批是恢复同步的一部分，则为表示此变更批中变更的下限的项 ID，该 ID 的长度是可变的。

  9. 一个工作量估计值部分。该工作量估计值部分包含以下元素。

    数据类型 以字节为单位的长度 说明

    ULONG

    4

    同步会话的工作量估计值。

    ULONG

    4

    此变更批的工作量估计值。

  10. 一个标志部分。该标志部分包含以下元素。

    数据类型 以字节为单位的长度 说明

    BYTE

    1

    指示此变更批是否为源提供程序发送的最后一个变更批。值为 0 表示这不是最后一个变更批。值为 1 表示这是最后一个变更批。

    BYTE

    1

    指示此变更批是否为恢复同步的组成部分。值为 0 表示此变更批不是恢复同步的组成部分。值为 1 表示此变更批是恢复同步的组成部分。

    BYTE

    1

    指示是否筛选此变更批。值为 0 表示不筛选此变更批。值为 1 表示筛选此变更批。

请参阅

参考

ISyncChangeBatchBase2 接口