ISyncKnowledge::Serialize

Serializes the knowledge object data to a byte array.

HRESULT Serialize( 
  BOOL fSerializeReplicaKeyMap,
  BYTE *pbKnowledge,
  DWORD *pcbKnowledge);

Parameters

• fSerializeReplicaKeyMap
  [in] TRUE to serialize the IReplicaKeyMap object that is contained in the knowledge; otherwise, FALSE.

• pbKnowledge
  [in, out, unique, size_is(*pcbKnowledge)] The byte array that receives the serialized knowledge data.

• pcbKnowledge
  [in, out] Specifies the number of bytes in pbKnowledge. Returns the number of bytes required to serialize the replica key map data when pbKnowledge is too small, or returns the number of bytes written.

Return Value

• S_OK.

• E_POINTER.

• E_INVALIDARG.

• E_OUTOFMEMORY.

• HRESULT_FROM_WIN32(ERROR_MORE_DATA) when pbKnowledge is too small. In this case, the required number of bytes is returned in pcbKnowledge.

Remarks

The proper IReplicaKeyMap Interface object is required to deserialize a knowledge object by using IProviderSyncServices::DeserializeSyncKnowledge. When FALSE is specified for fSerializeReplicaKeyMap, 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 pbKnowledge is stored in compact form, with no padding, in big-endian byte order. 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 major version of the serialization format. This value is always 3.
   ULONG	4	The minor version of the serialization format. This value is always 0.

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

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

   Data type	Length in bytes	Description
   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.

4. One scope clock vector section. The scope clock vector section 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 section 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.

5. One range exception section. The range exception section contains the following elements:

   Data type	Length in bytes	Description
   ULONG	4	The range exception section signature. This value is always 3.
   ULONG	4	The number of range exceptions that are contained in the knowledge.

   The range exception section contains a list of range exceptions, with the number of range exceptions equal to the value specified in the previous ULONG.

   Each range exception contains the following elements:

   Data type	Length in bytes	Description
   ULONG	4	The range exception signature. this value is always 2.

   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 of the lower bound item ID for the range.
   Sequence of bytes	The length specified in the item ID format.	The fixed-length item ID of the upper bound item ID for 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 of the lower bound item ID for the range.
   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 of the upper bound item ID for the range.

   The clock vector that is associated with the range exception:

   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.

6. One single item exception section. The single item exception section contains the following elements:

   Data type	Length in bytes	Description
   ULONG	4	The single item exception section signature. This value is always 6.
   ULONG	4	The clock vector table signature. This value is always 4.
   ULONG	4	The number of clock vectors that are contained in the clock vector table.

   1. A clock vector table. 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.

   2. A single item exception table. The single item exception table contains the following elements:

      Data type	Length in bytes	Description
      ULONG	4	The number of single item exceptions that are contained in the single item exception table.

      Each single item exception in the table 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 is associated with the single item exception.

      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 is associated with the single item exception.

      Each single item exception contains the following additional elements:

      Data type	Length in bytes	Description
      ULONG	4	When the single item exception refers to an item, this value is an index into the clock vector table that is contained in this serialized data. When the single item exception refers to one or more change unit exceptions, this value is 0xFFFFFFFF.
      ULONG	4	The number of change unit exceptions that are contained in the exception. This value may be 0.

      When change unit exceptions are present, a list of change unit exceptions follows. The list contains the number of change unit exceptions specified in the previous ULONG.

      Each change unit exception 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 that is associated with the change unit exception.

      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 that is associated with the change unit exception.

      Each change unit exception 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.

See Also

Reference

ISyncKnowledge Interface