ISyncKnowledge2::SerializeWithOptions

  • Article

Serializes the knowledge object data to a byte array based on the specified version and serialization options.

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

Parameters

Term

Definition

targetFormatVersion

[in] The serialized knowledge is compatible with this version.

dwFlags

[in] Options that specify additional information about how to serialize the object. Must be 0 or a combination of the values that are specified by the SYNC_SERIALIZE flags. When 0 is specified, the replica key map is not included as part of the serialized knowledge data.

pBuffer

[in, out, unique, size_is(*pdwSerializedSize)] The serialized knowledge object data is serialized to this buffer.

pdwSerializedSize

[in, out] Specifies the number of bytes in pBuffer. Returns either the number of bytes that are required to serialize the knowledge data when pBuffer is too small, or the number of bytes written.

Return Value

  • S_OK.

  • E_POINTER.

  • HRESULT_FROM_WIN32(ERROR_MORE_DATA) when pBuffer is too small. In this situation, the required number of bytes is returned in pdwSerializedSize.

  • SYNC_E_INVALID_VERSION when the value of targetFormatVersion is higher than the version of the object, or the object contains elements that are not compatible with targetFormatVersion.

Remarks

The value of targetFormatVersion determines the format of the serialized knowledge data. When SYNC_SERIALIZATION_VERSION_V1 is specified, the serialized format is compatible with Sync Framework 1.0 and later components. When SYNC_SERIALIZATION_VERSION_V2 is specified, the serialized format is compatible with Sync Framework 2.0 components. If SYNC_SERIALIZATION_VERSION_V2 is specified when the knowledge object contains elements that are not compatible with Sync Framework 1.0, SYNC_E_INVALID_VERSION is returned. For example, the knowledge that is returned by ISyncKnowledge2::ProjectOntoColumnSet contains elements that were introduced in Sync Framework 2.0, and so cannot be serialized with SYNC_SERIALIZATION_VERSION_V1 specified for targetFormatVersion.

Note

Serializing to the Sync Framework 1.0 format is less efficient than the Sync Framework 2.0 format. Unless there is a specific need for the Sync Framework 1.0 format, the Sync Framework 2.0 format should be used.

The proper IReplicaKeyMap Interface object is required to deserialize a knowledge object by using IProviderSyncServices::DeserializeSyncKnowledge. When SYNC_SERIALIZE_REPLICA_KEY_MAP is specified for flags, the IReplicaKeyMap object is serialized along with the knowledge data. When this flag is not specified, the IReplicaKeyMap data must be stored in some other way so that the knowledge object can be deserialized.

Serialization Format

The serialized knowledge that is contained in pBuffer is stored in compact form, with no padding, in big-endian byte order.

When targetFormatVersion is SYNC_SERIALIZATION_VERSION_V1, the knowledge is serialized according to the format described in ISyncKnowledge::Serialize. Otherwise, the serialized knowledge contains the following elements, in the following order.

  1. One header section. The header section contains the following elements:

    Data type Length in bytes Description

    ULONG

    4

    The version of the serialization format. This is the value contained in targetFormatVersion and must be a valid value from the SYNC_SERIALIZATION_VERSION enumeration.

    ULONG

    4

    Reserved. This value is always 0.

    ULONG

    4

    The minimum supported version of the serialized knowledge.

    ULONG

    4

    Reserved. This value is always 0.

  2. One replica key map section when dwFlags contains SYNC_SERIALIZE_REPLICA_KEY_MAP. Otherwise, no replica key map section is present. The format of the replica key map section is defined in IReplicaKeyMap::Serialize.

  3. A signature that indicates the next set of sections:

    Data type Length in bytes Description

    ULONG

    4

    The section signature. This value is always 24.

  4. One ID format schema section. The ID format schema section contains the following elements:

    Data type Length in bytes Description

    BOOL

    1

    Indicates whether replica IDs that are contained in the knowledge are fixed length or variable length. This value is 0 if the IDs are fixed length; or 1 if the IDs are variable length.

    USHORT

    2

    The length, in bytes, of replica IDs for fixed-length IDs, or the maximum length of the ID for variable-length IDs.

    BOOL

    1

    Indicates whether item IDs that are contained in the knowledge are fixed length or variable length. This value is 0 if the IDs are fixed length; or 1 if the IDs are variable length.

    USHORT

    2

    The length, in bytes, of item IDs for fixed-length IDs, or the maximum length of the ID for variable-length IDs.

    BOOL

    1

    Indicates whether change unit IDs that are contained in the knowledge are fixed length or variable length. This value is 0 if the IDs are fixed length; or 1 if the IDs are variable length.

    USHORT

    2

    The length, in bytes, of change unit IDs for fixed-length IDs, or the maximum length of the ID for variable-length IDs.

  5. One clock vector table section. The clock vector table section contains the following elements:

    Data type Length in bytes Description

    ULONG

    4

    The clock vector table signature. This value is always 21.

    ULONG

    4

    The number of clock vectors that are contained in the clock vector table.

  6. The clock vector table contains a list of clock vectors, with the number of clock vectors equal to the value specified in the previous ULONG. Each clock vector contains the following elements:

    Data type Length in bytes Description

    ULONG

    4

    The clock vector signature. This value is 1 when the clock vector does not contain FeedSync feed items; otherwise, the value is 9 when the clock vector contains FeedSync feed items.

    ULONG

    4

    The number of clock vector elements that are contained in this clock vector.

    When the clock vector contains FeedSync feed items, the following section exists in the serialized knowledge; otherwise, it does not exist:

    Data type Length in bytes Description

    ULONG

    4

    The number of updates that have been made to the FeedSync feed that is associated with this knowledge. This value corresponds to the updates attribute of the FeedSync feed.

    BYTE

    1

    Indicates whether the FeedSync feed tracks conflicts. This value corresponds to the noconflicts attribute of the FeedSync feed. This value is 0 when noconflicts is not set; otherwise, the value is 1.

    The remainder of the clock vector contains a list of the clock vector elements, with the number of elements equal to the value specified previously in the clock vector section.

    Each clock vector element contains the following elements:

    Data type Length in bytes Description

    ULONG

    4

    A replica key.

    ULONGLONG

    8

    A tick count.

    When the knowledge is associated with a FeedSync feed, each clock vector element contains the following additional elements:

    Data type Length in bytes Description

    ULONG

    4

    The date portion of the when value of the FeedSync feed.

    ULONG

    4

    The time portion of the when value of the FeedSync feed.

    BYTE

    1

    The flags associated with the FeedSync feed.

  7. One range set section. The range set section contains the following elements:

    Data type Length in bytes Description

    ULONG

    4

    The range set section signature. This value is always 23.

    ULONG

    4

    The number of range sets that are included in this section.

    The range set section contains a list of range sets, with the number of range sets equal to the value specified in the previous ULONG. The first range set is the scope range set.

    Each range set contains the following elements:

    Data type Length in bytes Description

    ULONG

    4

    The range set signature. This value is always 22.

    ULONG

    4

    The number of ranges that are included in this range set.

    Each range in the range set contains the following elements:

    When item IDs are fixed length:

    Data type Length in bytes Description

    Sequence of bytes

    The length specified in the item ID format.

    The fixed-length item ID that begins the range.

    Or, when item IDs are variable length:

    Data type Length in bytes Description

    USHORT

    2

    The length, in bytes, of the variable-length ID. This length includes the two bytes for the USHORT that contains the length, plus the bytes that contain the actual ID.

    Sequence of bytes

    The length specified in the previous USHORT.

    The variable-length item ID that begins the range.

    Each range contains the following additional element:

    Data type Length in bytes Description

    ULONG

    4

    An index into the clock vector table that is contained in this serialized data.

  8. One column set section. The column set section contains the following elements:

    Data type Length in bytes Description

    ULONG

    4

    The number of columns that are included in this section.

    Each column in the column set section contains the following elements:

    When change unit IDs are fixed length:

    Data type Length in bytes Description

    Sequence of bytes

    The length specified in the change unit ID format.

    The fixed-length change unit ID.

    Or, when change unit IDs are variable length:

    Data type Length in bytes Description

    USHORT

    2

    The length, in bytes, of the variable-length ID. This length includes the two bytes for the USHORT that contains the length, plus the bytes that contain the actual ID.

    Sequence of bytes

    The length specified in the previous USHORT.

    The variable-length change unit ID.

    Each column in the column set section contains the following additional element:

    Data type Length in bytes Description

    ULONG

    4

    An index into the range set section that is contained in this serialized data.

  9. When targetFormatVersion is SYNC_SERIALIZATION_VERSION_V3 or higher, the serialized data contains one marker set section. The marker set section contains the following elements:

    Data type Length in bytes Description

    ULONG

    4

    The marker set section signature. This value is always 25.

    BOOL

    1

    Indicates whether the items listed in this section contain all change units or require all change units. This value is 0 when change units are present, or 1 when change units are required. Only one of these marker types can be present.

    ULONG

    4

    The number of items IDs listed in this section.

    The marker set section contains a list of item IDs, with the number of IDs equal to the value contained in the previous ULONG.

    Each item ID contains the following elements:

    When item IDs are fixed length:

    Data type Length in bytes Description

    Sequence of bytes

    The length specified in the item ID format.

    The fixed-length item ID.

    Or, when item IDs are variable length:

    Data type Length in bytes Description

    USHORT

    2

    The length, in bytes, of the variable-length ID. This length includes the two bytes for the USHORT that contains the length, plus the bytes that contain the actual ID.

    Sequence of bytes

    The length specified in the previous USHORT.

    The variable-length item ID.

See Also

Reference

ISyncKnowledge2 Interface