Share via

ISyncChangeBatchBase2::SerializeWithOptions

  • Article

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

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

Parameters

Term

Definition

targetFormatVersion

[in] The serialized change batch is compatible with this version.

dwFlags

[in] Reserved. Must be 0.

pbBuffer

[in, out, unique, size_is(*pdwSerializedSize)] The serialized change batch 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 change batch data when pBuffer is too small, or the number of bytes written.

Return Value

  • S_OK.

  • E_INVALIDARG when dwFlags is not 0, or when the version that is specified by targetFormatVersion is incompatible with the change batch object data.

  • E_OUTOFMEMORY.

  • 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_OPERATION when the change batch contains a group that was started but not ended.

  • 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 change batch 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 change batch object contains elements that are not compatible with Sync Framework 1.0, E_INVALIDARG or SYNC_E_INVALID_OPERATION is returned.

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.

Serialization Format

The serialized change batch that is contained in pbBuffer is stored in compact form, with no padding, in big-endian byte order. The serialized change batch 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

    ULONGLONG

    8

    The version of the serialization format of the change batch. This value is 3 when targetFormatVersion is SYNC_SERIALIZATION_VERSION_V1, 4 when targetFormatVersion is SYNC_SERIALIZATION_VERSION_V2, and 5 when targetFormatVersion is SYNC_SERIALIZATION_VERSION_V3.

  2. One filter information section when targetFormatVersion is SYNC_SERIALIZATION_VERSION_V2, and filter information is present in the change batch. The filter information section contains the following elements.

    Data type Length in bytes Description

    ULONG

    4

    The length, in bytes, of the filter information section.

    The remainder of the filter information section is in the format described in ISyncFilterInfo::Serialize.

  3. One destination knowledge section. The destination knowledge section contains the following elements.

    Data type Length in bytes Description

    ULONG

    4

    The length, in bytes, of the destination knowledge section. This length may be 0, in which case no destination knowledge follows.

    Sequence of bytes

    The length specified in the previous ULONG.

    When targetFormatVersion is SYNC_SERIALIZATION_VERSION_V1, the destination knowledge is in the format described by ISyncKnowledge::Serialize. Otherwise, the destination knowledge is in the format described by ISyncKnowledge2::SerializeWithOptions. The serialized destination knowledge always contains the serialized replica key map.

  4. One source forgotten knowledge section. The source forgotten knowledge section contains the following elements.

    Data type Length in bytes Description

    ULONG

    4

    The length, in bytes, of the source forgotten knowledge section. This length may be 0, in which case no source forgotten knowledge follows.

    Sequence of bytes

    The length specified in the previous ULONG.

    When targetFormatVersion is SYNC_SERIALIZATION_VERSION_V1, the source forgotten knowledge is in the format described by ISyncKnowledge::Serialize. Otherwise, the source forgotten knowledge is in the format described by ISyncKnowledge2::SerializeWithOptions. The serialized source forgotten knowledge always contains the serialized replica key map.

  5. One source filter key map section when targetFormatVersion is SYNC_SERIALIZATION_VERSION_V3, and source filter key map information is present. The source filter key map section contains the following elements.

    Data type Length in bytes Description

    ULONG

    4

    The length, in bytes, of the source filter key map section. This length may be 0, in which case no source filter key map follows.

    USHORT

    2

    The version of the serialization format of the filter key map. This value is SYNC_SERIALIZATION_VERSION_V3.

    ULONG

    4

    The number of filters in the filter key map.

    Each filter in the filter key map contains the following elements.

    Data type Length in bytes Description

    ULONG

    4

    The length, in bytes, of the filter.

    Sequence of bytes

    The length specified in the previous ULONG.

    The serialized filter data that was written to the stream by the ISyncFilter::Serialize method.

  6. One made-with knowledge section. The made-with knowledge section contains the following elements.

    Data type Length in bytes Description

    ULONG

    4

    The number of made-with knowledge objects that are contained in the serialized data. This number may be 0, in which case no made-with knowledge follows.

    Each made-with knowledge contains the following elements.

    Data type Length in bytes Description

    ULONG

    4

    The length, in bytes, of the made-with knowledge.

    Sequence of bytes

    The length specified in the previous ULONG.

    When targetFormatVersion is SYNC_SERIALIZATION_VERSION_V1, the made-with knowledge is in the format described by ISyncKnowledge::Serialize. Otherwise, the made-with knowledge is in the format described by ISyncKnowledge2::SerializeWithOptions. The serialized made-with knowledge always contains the serialized replica key map.

  7. One change set section. The change set section contains the following elements.

    Data type Length in bytes Description

    ULONG

    4

    The number of change objects that are contained in the serialized data. This number may be 0, in which case no changes follow.

    Each change contains the following elements.

    Data type Length in bytes Description

    ULONG

    4

    The length, in bytes, of the change data.

    ULONGLONG

    8

    The signature of the serialization format of the change object. This value is 5 when targetFormatVersion is SYNC_SERIALIZATION_VERSION_V1 or SYNC_SERIALIZATION_VERSION_V2, and 6 when targetFormatVersion is SYNC_SERIALIZATION_VERSION_V3.

    When replica IDs are fixed length.

    Data type Length in bytes Description

    Sequence of bytes

    The length specified in the replica ID format.

    The fixed-length replica ID.

    Or, when replica 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 replica ID.

    Each change contains the following additional elements.

    Data type Length in bytes Description

    ULONG

    4

    The replica key that identifies which replica made this change.

    ULONGLONG

    8

    The tick count of the replica that made this change.

    ULONG

    4

    Reserved. This value can be ignored.

    ULONGLONG

    8

    Reserved. This value can be ignored.

    ULONG

    4

    The replica key that identifies the replica that created this item.

    ULONGLONG

    8

    The tick count of the replica that created this item.

    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.

    When targetFormatVersion is SYNC_SERIALIZATION_VERSION_V3 or higher, each change contains the following additional elements.

    Data type Length in bytes Description

    BOOL

    1

    Indicates whether a winner ID exists in the serialized data. A value of 0 indicates no winner ID follows. A value of 1 indicates a winner ID follows.

    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 winner 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 winner ID.

    Every change contains the following additional elements.

    Data type Length in bytes Description

    ULONG

    4

    The flags associated with the change. This is a combination of the SYNC_CHANGE_FLAG flags.

    ULONG

    4

    The work estimate for the change.

    USHORT

    2

    Reserved. This value is always 0.

    BYTE

    1

    Indicates whether the learned knowledge that is associated with this change is projected onto this item. A value of 0 indicates that the learned knowledge is not projected. A value of 1 indicates that the learned knowledge is projected.

    ULONG

    4

    An index into the made-with knowledge list contained in this serialized data. This value may be 0, which indicates that a made-with knowledge is not associated with this change.

    ULONG

    4

    The number of change units that are contained in this change. This value may be 0, in which case no change units follow.

    The change contains a list of change units, with the number of change units equal to the value contained in the previous ULONG.

    Each change unit 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 change unit contains the following additional elements.

    Data type Length in bytes Description

    ULONG

    4

    The replica key that identifies the replica that made this change.

    ULONGLONG

    8

    The tick count of the replica that made this change.

    ULONG

    4

    Reserved. This value is always 0.

    ULONGLONG

    8

    Reserved. This value is always 0.

  8. One recovery synchronization section. The recovery synchronization section contains the following elements.

    Data type Length in bytes Description

    ULONG

    4

    The length, in bytes, of the recovery synchronization section. When this value is 0, no recovery synchronization section follows.

    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 represents the lower bound of the changes in this change batch, when the change batch is part of a recovery synchronization.

    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 represents the lower bound of the changes in this change batch, when the change batch is part of a recovery synchronization.

  9. One work estimate section. The work estimate section contains the following elements.

    Data type Length in bytes Description

    ULONG

    4

    The work estimate of the synchronization session.

    ULONG

    4

    The work estimate of this change batch.

  10. One flags section. The flags section contains the following elements.

    Data type Length in bytes Description

    BYTE

    1

    Indicates whether this change batch is the last change batch sent by the source provider. A value of 0 indicates that this is not the last change batch. A value of 1 indicates that this is the last change batch.

    BYTE

    1

    Indicates whether this change batch is part of a recovery synchronization. A value of 0 indicates that this change batch is not part of a recovery synchronization. A value of 1 indicates this change batch is part of a recovery synchronization.

    BYTE

    1

    Indicates whether this change batch is filtered. A value of 0 indicates that this change batch is not filtered. A value of 1 indicates that this change batch is filtered.

See Also

Reference

ISyncChangeBatchBase2 Interface