共用方式為

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 中所包含的序列化知識儲存在以位元組由大到小順序排列的壓縮模式中，不帶填補。

當 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. 一個識別碼格式結構描述區段。識別碼格式結構描述區段包含下列元素：

    資料類型 長度 (以位元組為單位) 描述

    BOOL

    1

    表示知識中所包含的複寫識別碼是固定長度還是變動長度。如果識別碼是固定長度，這個值是 0，如果識別碼是變動長度，則為 1。

    USHORT

    2

    固定長度識別碼的複寫識別碼長度 (以位元組為單位)，或變動長度識別碼的最大識別碼長度。

    BOOL

    1

    表示知識中所包含的項目識別碼是固定長度還是變動長度。如果識別碼是固定長度，這個值是 0，如果識別碼是變動長度，則為 1。

    USHORT

    2

    固定長度識別碼的項目識別碼長度 (以位元組為單位)，或變動長度識別碼的最大識別碼長度。

    BOOL

    1

    表示知識中所包含的變更單位識別碼是固定長度還是變動長度。如果識別碼是固定長度，這個值是 0，如果識別碼是變動長度，則為 1。

    USHORT

    2

    固定長度識別碼的變更單位識別碼長度 (以位元組為單位)，或變動長度識別碼的最大識別碼長度。

  5. 一個時鐘向量資料表區段。時鐘向量資料表區段包含下列元素：

    資料類型 長度 (以位元組為單位) 描述

    ULONG

    4

    時鐘向量資料表簽章。這個值一定是 21。

    ULONG

    4

    時鐘向量資料表內所包含的時鐘向量數目。

  6. 時鐘向量資料表包含時鐘向量的清單，其中的時鐘向量數目等於先前在 ULONG 中指定的值。每個時鐘向量都包含下列元素：

    資料類型 長度 (以位元組為單位) 描述

    ULONG

    4

    時鐘向量簽章。當時鐘向量不包含 FeedSync 摘要項目時，這個值為 1，當時鐘向量包含 FeedSync 摘要項目時，這個值則為 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

    這個範圍設定中所包含的範圍數目。

    範圍設定中的每個範圍都包含下列元素：

    當項目識別碼為固定長度時：

    資料類型 長度 (以位元組為單位) 描述

    位元組順序

    在項目識別碼格式中指定的長度。

    範圍開頭的固定長度項目識別碼。

    或者，當項目識別碼為變動長度時：

    資料類型 長度 (以位元組為單位) 描述

    USHORT

    2

    變動長度識別碼的長度 (以位元組為單位)。此長度包含內含長度之 USHORT 的兩個位元組，加上包含實際識別碼的位元組。

    位元組順序

    在先前的 USHORT 中指定的長度。

    範圍開頭的變動長度項目識別碼。

    每個範圍都包含下列其他元素：

    資料類型 長度 (以位元組為單位) 描述

    ULONG

    4

    包含在此序列化資料中，時鐘向量資料表的索引。

  8. 一個資料行集區段。資料行集區段包含下列元素：

    資料類型 長度 (以位元組為單位) 描述

    ULONG

    4

    這個區段中所包含的資料行數目。

    資料行集區段中的每個資料行都包含下列元素：

    當變更單位識別碼為固定長度時：

    資料類型 長度 (以位元組為單位) 描述

    位元組順序

    在變更單位識別碼格式中指定的長度。

    固定長度的變更單位識別碼。

    或者，當變更單位識別碼為變動長度時：

    資料類型 長度 (以位元組為單位) 描述

    USHORT

    2

    變動長度識別碼的長度 (以位元組為單位)。此長度包含內含長度之 USHORT 的兩個位元組，加上包含實際識別碼的位元組。

    位元組順序

    在先前的 USHORT 中指定的長度。

    變動長度的變更單位識別碼。

    資料行集區段中的每個資料行都包含下列其他元素：

    資料類型 長度 (以位元組為單位) 描述

    ULONG

    4

    包含在此序列化資料中，範圍設定區段的索引。

  9. 當 targetFormatVersion 是 SYNC_SERIALIZATION_VERSION_V3 或更高時，序列化的資料就會包含單一標記集區段。標記集區段包含下列元素：

    資料類型 長度 (以位元組為單位) 描述

    ULONG

    4

    標記集區段簽章。這個值一定是 25。

    BOOL

    1

    指出這個區段中所列的項目會包含所有變更單位，還是需要所有變更單位。當變更單位存在時，這個值是 0，當需要變更單位時，這個值是 1。只能存在其中一種標記類型。

    ULONG

    4

    在這個區段中所列的項目識別碼數目。

    標記集區段包含項目識別碼的清單，其中的識別碼數目等於先前包含在 ULONG 中的值。

    每個項目識別碼都包含下列元素：

    當項目識別碼為固定長度時：

    資料類型 長度 (以位元組為單位) 描述

    位元組順序

    在項目識別碼格式中指定的長度。

    固定長度項目識別碼。

    或者，當項目識別碼為變動長度時：

    資料類型 長度 (以位元組為單位) 描述

    USHORT

    2

    變動長度識別碼的長度 (以位元組為單位)。此長度包含內含長度之 USHORT 的兩個位元組，加上包含實際識別碼的位元組。

    位元組順序

    在先前的 USHORT 中指定的長度。

    變動長度項目識別碼。

請參閱

參考

ISyncKnowledge2 介面