ISyncChangeBatchBase2::SerializeWithOptions

根據指定的版本和序列化選項，將變更批次物件資料序列化為位元組陣列。

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

參數

術語	定義
targetFormatVersion	[in] 序列化的變更批次與這個版本相容。
dwFlags	[in] 已保留。必須是 0。
pbBuffer	[in, out, unique, size_is(*pdwSerializedSize)] 序列化的變更批次物件資料會序列化至這個緩衝區。
pdwSerializedSize	[in, out] 指定 pBuffer 中的位元組數目。當 pBuffer 太小時，就傳回序列化此變更批次資料所需的位元組數目，否則就傳回寫入的位元組數目。

傳回值

• S_OK。

• 如果 dwFlags 不是 0，或者 targetFormatVersion 指定的版本與變更批次物件資料不相容，則為 E_INVALIDARG。

• E_OUTOFMEMORY。

• E_POINTER。

• 當 pBuffer 太小時，為 HRESULT_FROM_WIN32(ERROR_MORE_DATA)。在這種情況下，所需的位元組數目是在 pdwSerializedSize 中傳回。

• 如果變更批次包含已啟動但尚未結束的群組，為 SYNC_E_INVALID_OPERATION。

• 如果 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，就會傳回 E_INVALIDARG 或 SYNC_E_INVALID_OPERATION。

注意

序列化至 Sync Framework 1.0 格式的效率低於 Sync Framework 2.0 格式。除非您有 Sync Framework 1.0 格式的特定需求，否則就應該使用 Sync Framework 2.0 格式。

序列化格式

pbBuffer 中所包含的序列化變更批次儲存在以位元組由大到小順序排列的壓縮模式中，不帶填補。序列化的變更批次包含下列元素 (依下列順序)。

1. 一個標頭區段。標頭區段包含下列元素。

   資料類型	長度 (以位元組為單位)	描述
   ULONGLONG	8	變更批次之序列化格式的版本。當 targetFormatVersion 為 SYNC_SERIALIZATION_VERSION_V1 時，此值為 3；當 targetFormatVersion 為 SYNC_SERIALIZATION_VERSION_V2 時，此值為 4；而當 targetFormatVersion 為 SYNC_SERIALIZATION_VERSION_V3 時，此值為 5。

2. 當 targetFormatVersion 為 SYNC_SERIALIZATION_VERSION_V2，而且在變更批次中有篩選資訊時，為一個篩選資訊區段。篩選資訊區段包含下列元素。

   資料類型	長度 (以位元組為單位)	描述
   ULONG	4	篩選資訊區段的長度 (以位元組為單位)。

   篩選資訊區段的其餘部分是依照 ISyncFilterInfo::Serialize 中所描述的格式。

3. 一個目的地知識區段。目的地知識區段包含下列元素。

   資料類型	長度 (以位元組為單位)	描述
   ULONG	4	目的地知識區段的長度 (以位元組為單位)。此長度可能為 0，在這種情況下，後面沒有目的地知識。
   位元組順序	在先前的 ULONG 中指定的長度。	當 targetFormatVersion 是 SYNC_SERIALIZATION_VERSION_V1 時，目的地知識會採用 ISyncKnowledge::Serialize 中所描述的格式。否則，目的地知識會採用 ISyncKnowledge2::SerializeWithOptions 所描述的格式。序列化的目的地知識一律包含序列化的複寫機碼對應。

4. 一個來源被遺忘的知識區段。來源被遺忘的知識區段包含下列元素。

   資料類型	長度 (以位元組為單位)	描述
   ULONG	4	來源被遺忘的知識區段的長度 (以位元組為單位)。此長度可能為 0，在這種情況下，後面沒有來源被遺忘的知識。
   位元組順序	在先前的 ULONG 中指定的長度。	當 targetFormatVersion 是 SYNC_SERIALIZATION_VERSION_V1 時，來源被遺忘的知識會採用 ISyncKnowledge::Serialize 中所描述的格式。否則，來源被遺忘的知識會採用 ISyncKnowledge2::SerializeWithOptions 所描述的格式。序列化的來源被遺忘知識一律包含序列化的複寫機碼對應。

5. One source filter key map section 當 targetFormatVersion 為 SYNC_SERIALIZATION_VERSION_V3 時，有一個來源篩選機碼對應區段，並且有來源篩選機碼對應資訊。這個來源篩選機碼對應區段包含下列元素。

   資料類型	長度 (以位元組為單位)	描述
   ULONG	4	來源篩選機碼對應區段的長度 (以位元組為單位)。此長度可能為 0，在這種情況下，後面沒有來源篩選機碼對應。
   USHORT	2	篩選機碼對應之序列化格式的版本。這項值為 SYNC_SERIALIZATION_VERSION_V3。
   ULONG	4	篩選機碼對應中的篩選數目。

   篩選機碼對應中的每個篩選都包含下列元素。

   資料類型	長度 (以位元組為單位)	描述
   ULONG	4	篩選的長度 (以位元組為單位)。
   位元組順序	在先前的 ULONG 中指定的長度。	由 ISyncFilter::Serialize 方法寫入資料流的序列化篩選資料。

6. 一個建立方式知識區段。建立方式知識區段包含下列元素。

   資料類型	長度 (以位元組為單位)	描述
   ULONG	4	包含在序列化資料中的建立方式知識物件數目。此數字可能為 0，在這種情況下，後面沒有建立方式知識。

   每個建立方式知識都包含下列元素。

   資料類型	長度 (以位元組為單位)	描述
   ULONG	4	建立方式知識的長度 (以位元組為單位)。
   位元組順序	在先前的 ULONG 中指定的長度。	當 targetFormatVersion 是 SYNC_SERIALIZATION_VERSION_V1 時，建立方式知識會採用 ISyncKnowledge::Serialize 中所描述的格式。否則，建立方式知識會採用 ISyncKnowledge2::SerializeWithOptions 所描述的格式。序列化的建立方式知識一律包含序列化的複寫機碼對應。

7. 一個變更集區段。變更集區段包含下列元素。

   資料類型	長度 (以位元組為單位)	描述
   ULONG	4	包含在序列化資料中的變更物件數目。這個數字可能為 0，在這種情況下，後面沒有任何變更。

   每個變更都包含下列元素。

   資料類型	長度 (以位元組為單位)	描述
   ULONG	4	變更資料的長度 (以位元組為單位)。
   ULONGLONG	8	變更物件之序列化格式的簽章。當 targetFormatVersion 為 SYNC_SERIALIZATION_VERSION_V1 或 SYNC_SERIALIZATION_VERSION_V2 時，此值為 5；而當 targetFormatVersion 為 SYNC_SERIALIZATION_VERSION_V3 時，此值為 6。

   當複寫識別碼為固定長度時。

   資料類型	長度 (以位元組為單位)	描述
   位元組順序	在複寫識別碼格式中指定的長度。	固定長度複寫識別碼。

   或者，當複寫識別碼為可變長度時。

   資料類型	長度 (以位元組為單位)	描述
   USHORT	2	可變長度識別碼的長度 (以位元組為單位)。此長度包含內含長度之 USHORT 的兩個位元組，加上包含實際識別碼的位元組。
   位元組順序	在先前的 USHORT 中指定的長度。	可變長度複寫識別碼。

   每個變更都包含下列其他元素。

   資料類型	長度 (以位元組為單位)	描述
   ULONG	4	識別哪個複寫進行此變更的複寫機碼。
   ULONGLONG	8	進行此變更之複寫的滴答計數。
   ULONG	4	已保留。這個值可以忽略。
   ULONGLONG	8	已保留。這個值可以忽略。
   ULONG	4	識別建立此項目之複寫的複寫機碼。
   ULONGLONG	8	建立此項目之複寫的滴答計數。

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

   資料類型	長度 (以位元組為單位)	描述
   位元組順序	在項目識別碼格式中指定的長度。	固定長度項目識別碼。

   或者，當項目識別碼為可變長度時。

   資料類型	長度 (以位元組為單位)	描述
   USHORT	2	可變長度識別碼的長度 (以位元組為單位)。此長度包含內含長度之 USHORT 的兩個位元組，加上包含實際識別碼的位元組。
   位元組順序	在先前的 USHORT 中指定的長度。	可變長度項目識別碼。

   當 targetFormatVersion 為 SYNC_SERIALIZATION_VERSION_V3 或更高時，每個變更都包含下列其他元素。

   資料類型	長度 (以位元組為單位)	描述
   BOOL	1	指出在序列化的資料中是否存在成功者識別碼。值為 0 時，表示後面沒有成功者識別碼。值為 1 時，表示後面有一個成功者識別碼。

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

   資料類型	長度 (以位元組為單位)	描述
   位元組順序	在項目識別碼格式中指定的長度。	固定長度成功者識別碼。

   或者，當項目識別碼為可變長度時。

   資料類型	長度 (以位元組為單位)	描述
   USHORT	2	可變長度識別碼的長度 (以位元組為單位)。此長度包含內含長度之 USHORT 的兩個位元組，加上包含實際識別碼的位元組。
   位元組順序	在先前的 USHORT 中指定的長度。	可變長度成功者識別碼。

   每個變更都包含下列其他元素。

   資料類型	長度 (以位元組為單位)	描述
   ULONG	4	與變更相關聯的旗標。這是 SYNC_CHANGE_FLAG 旗標的組合。
   ULONG	4	此變更的工作量估計值。
   USHORT	2	已保留。這個值一定是 0。
   BYTE	1	表示與此變更相關聯之學習到的知識是否投射到這個項目。值為 0 時，表示沒有投射學習到的知識。值為 1 時，表示有投射學習到的知識。
   ULONG	4	包含在此序列化資料之建立方式知識清單中的索引。這個值可能為 0，建立方式知識與此變更沒有關聯。
   ULONG	4	包含在此變更中的變更單位數目。這個值可能為 0，在這種情況下，後面沒有任何變更單位。

   此變更包含變更單位的清單，其中的變更單位數目等於先前包含在 ULONG 中的值。

   每個變更單位都包含下列元素。

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

   資料類型	長度 (以位元組為單位)	描述
   位元組順序	在變更單位識別碼格式中指定的長度。	固定長度的變更單位識別碼。

   或者，當變更單位識別碼為可變長度時。

   資料類型	長度 (以位元組為單位)	描述
   USHORT	2	可變長度識別碼的長度 (以位元組為單位)。此長度包含內含長度之 USHORT 的兩個位元組，加上包含實際識別碼的位元組。
   位元組順序	在先前的 USHORT 中指定的長度。	可變長度的變更單位識別碼。

   每個變更單位都包含下列其他元素。

   資料類型	長度 (以位元組為單位)	描述
   ULONG	4	識別進行此變更之複寫的複寫機碼。
   ULONGLONG	8	進行此變更之複寫的滴答計數。
   ULONG	4	已保留。這個值一定是 0。
   ULONGLONG	8	已保留。這個值一定是 0。

8. 一個復原同步處理區段復原同步處理區段包含下列元素。

   資料類型	長度 (以位元組為單位)	描述
   ULONG	4	復原同步處理區段的長度 (以位元組為單位)。此值為 0 時，後面沒有復原同步處理區段。

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

   資料類型	長度 (以位元組為單位)	描述
   位元組順序	在項目識別碼格式中指定的長度。	當變更批次是復原同步處理的一部分時，這是表示此變更批次中變更下限的固定長度項目識別碼。

   或者，當項目識別碼為可變長度時。

   資料類型	長度 (以位元組為單位)	描述
   USHORT	2	可變長度識別碼的長度 (以位元組為單位)。此長度包含內含長度之 USHORT 的兩個位元組，加上包含實際識別碼的位元組。
   位元組順序	在先前的 USHORT 中指定的長度。	當變更批次是復原同步處理的一部分時，這是表示此變更批次中變更下限的可變長度項目識別碼。

9. 一個工作量估計值區段。工作量估計值區段包含下列元素。

   資料類型	長度 (以位元組為單位)	描述
   ULONG	4	同步處理工作階段的工作量估計值。
   ULONG	4	此變更批次的工作量估計值。

10. 一個旗標區段。旗標區段包含下列元素。

    資料類型	長度 (以位元組為單位)	描述
    BYTE	1	指出此變更批次是否為來源提供者傳送的最後一個變更批次。值為 0 時，表示這不是最後一個變更批次。值為 1 時，表示這是最後一個變更批次。
    BYTE	1	指出此變更批次是否屬於復原同步處理的一部分。值為 0 時，表示這個變更批次不屬於復原同步處理的一部分。值為 1 時，表示這個變更批次屬於復原同步處理的一部分。
    BYTE	1	指出是否篩選此變更批次。值為 0 時，表示未篩選此變更批次。值為 1 時，表示已篩選此變更批次。

請參閱

參考

ISyncChangeBatchBase2 介面