通过

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。

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

  • 如果 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，则返回 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 中的序列化知识以压缩形式（没有填充）并按 Big-Endian 字节顺序存储。

当 targetFormatVersion 为 SYNC_SERIALIZATION_VERSION_V1 时，将基于 ISyncKnowledge::Serialize 中介绍的格式序列化知识。否则，序列化知识将按下面的顺序包含以下元素。

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

    数据类型

    以字节为单位的长度

    说明

    ULONG

    4

    序列化格式的版本。这是 targetFormatVersion 中包含的值，并且必须是 SYNC_SERIALIZATION_VERSION 枚举中的一个有效值。

    ULONG

    4

    保留。此值始终为 0。

    ULONG

    4

    序列化知识支持的最低版本。

    ULONG

    4

    保留。此值始终为 0。

  2. 当 dwFlags 包含 SYNC_SERIALIZE_REPLICA_KEY_MAP 时，将显示一个副本键映射部分。否则，将不显示副本键映射部分。副本键映射部分的格式在 IReplicaKeyMap::Serialize 中定义。

  3. 指示下一组部分的签名：

    数据类型

    以字节为单位的长度

    说明

    ULONG

    4

    该部分签名。此值始终为 24。

  4. 一个 ID 格式架构部分。该 ID 格式架构部分包含以下元素：

    数据类型

    以字节为单位的长度

    说明

    BOOL

    1

    指示包含在知识中的副本 ID 是固定长度还是可变长度。如果副本 ID 是固定长度，则此值为 0；如果副本 ID 是可变长度，则此值为 1。

    USHORT

    2

    固定长度的副本 ID 的长度，或可变长度 ID 的最大长度（以字节为单位）。

    BOOL

    1

    指示包含在知识中的项 ID 是固定长度还是可变长度。如果项 ID 是固定长度，则此值为 0；如果项 ID 是可变长度，则此值为 1。

    USHORT

    2

    固定长度的项 ID 的长度（以字节为单位），或可变长度的项 ID 的最大长度。

    BOOL

    1

    指示包含在知识中的变更单位 ID 是固定长度还是可变长度。如果变更单位 ID 是固定长度，则此值为 0；如果变更单位 ID 是可变长度，则此值为 1。

    USHORT

    2

    固定长度的变更单位 ID 的长度，或可变长度的变更单位 ID 的最大长度（以字节为单位）。

  5. 一个时钟向量表部分。该时钟向量表部分包含以下元素：

    数据类型

    以字节为单位的长度

    说明

    ULONG

    4

    时钟向量表签名。此值始终为 21。

    ULONG

    4

    时钟向量表中包含的时钟向量的数量。

  6. 时钟向量表包含一个时钟向量列表，其中的时钟向量数与上一个 ULONG 中指定的数值相等。每个时钟向量都包含以下元素：

    数据类型

    以字节为单位的长度

    说明

    ULONG

    4

    时钟向量签名。如果时钟向量不包含 FeedSync 馈送项，则此值为 1；否则此值为 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. 一个范围集部分。该范围集部分包含以下元素：

    数据类型

    以字节为单位的长度

    说明

    ULONG

    4

    范围集部分签名。此值始终为 23。

    ULONG

    4

    此部分中包含的范围集的数量。

    该范围集部分包含一个范围集列表，其中的范围集数量与上一个 ULONG 中指定的数值相等。第一个范围集是作用域范围集。

    每个范围集都包含以下元素：

    数据类型

    以字节为单位的长度

    说明

    ULONG

    4

    范围集签名。此值始终为 22。

    ULONG

    4

    此范围集中包含的范围的数量。

    该范围集中的每个范围都包含以下元素：

    当项 ID 为固定长度时：

    数据类型

    以字节为单位的长度

    说明

    字节序列

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

    作为范围起始点的固定长度项 ID。

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

    数据类型

    以字节为单位的长度

    说明

    USHORT

    2

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

    字节序列

    上一个 USHORT 中指定的长度。

    作为范围起始点的可变长度项 ID。

    每个范围都包含以下附加元素：

    数据类型

    以字节为单位的长度

    说明

    ULONG

    4

    包含在此序列化数据中的时钟向量表中的索引。

  8. 列集部分。该列集部分包含以下元素：

    数据类型

    以字节为单位的长度

    说明

    ULONG

    4

    此部分中包含的列的数量。

    该列集部分中的每一列都包含以下元素：

    当变更单位 ID 是固定长度时：

    数据类型

    以字节为单位的长度

    说明

    字节序列

    以变更单位 ID 格式指定的长度。

    固定长度的变更单位 ID。

    或者，当变更单位 ID 是可变长度时：

    数据类型

    以字节为单位的长度

    说明

    USHORT

    2

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

    字节序列

    上一个 USHORT 中指定的长度。

    可变长度的变更单位 ID。

    该列集部分中的每一列都包含以下附加元素：

    数据类型

    以字节为单位的长度

    说明

    ULONG

    4

    包含在此序列化数据中的范围集部分中的索引。

  9. 当 targetFormatVersion 为 SYNC_SERIALIZATION_VERSION_V3 或更高版本时，序列化数据包含一个标记集部分。该标记集部分包含以下元素：

    数据类型

    以字节为单位的长度

    说明

    ULONG

    4

    标记集部分签名。此值始终为 25。

    BOOL

    1

    指示此部分中列出的项是包含所有变更单位，还是需要所有变更单位。如果包含变更单位，则此值为 0；否则如果需要变更单位，则此值为 1。只能包含这些标记类型中的一种。

    ULONG

    4

    此部分中列出的项 ID 的数量。

    该标记集部分包含一个项 ID 列表，其中的 ID 数量与上一个 ULONG 中的值相等。

    每个项 ID 都包含以下元素：

    当项 ID 为固定长度时：

    数据类型

    以字节为单位的长度

    说明

    字节序列

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

    固定长度的项 ID。

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

    数据类型

    以字节为单位的长度

    说明

    USHORT

    2

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

    字节序列

    上一个 USHORT 中指定的长度。

    可变长度的项 ID。

请参阅

其他资源

ISyncKnowledge2 接口