Поделиться через

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.

  • E_INVALIDARG, если параметр dwFlags не равен 0, либо если версия, указанная в параметре targetFormatVersion, несовместима с данными объекта пакета изменений.

  • E_OUTOFMEMORY.

  • E_POINTER.

  • HRESULT_FROM_WIN32(ERROR_MORE_DATA), если значение pBuffer слишком мало. В этом случае необходимое число байтов возвращается в параметре pdwSerializedSize.

  • SYNC_E_INVALID_OPERATION, если пакет изменений содержит группу, которая была начата, но не была завершена.

  • SYNC_E_INVALID_VERSION, если значение targetFormatVersion превышает номер версии объекта или объект содержит элементы, несовместимые с targetFormatVersion.

Замечания

Значение targetFormatVersion определяет формат сериализованных данных пакета изменений. Если указано значение SYNC_SERIALIZATION_VERSION_V1, то формат сериализации совместим с компонентами Sync Framework 1.0 и более поздних версий. Если указано значение SYNC_SERIALIZATION_VERSION_V2, то формат сериализации совместим с компонентами Sync Framework 2.0. Если указано значение SYNC_SERIALIZATION_VERSION_V2, а объект пакета изменений содержит элементы, не совместимые с платформой Sync Framework 1.0, возвращается значение E_INVALID_VERSION или SYNC_E_INVALID_OPERATION.

Примечание

Сериализация в формате Sync Framework 1.0 менее эффективна по сравнению с форматом Sync Framework 2.0. За исключением случаев, когда явно необходим формат Sync Framework 1.0, следует применять формат Sync Framework 2.0.

Формат сериализации

Сериализованный пакет изменений, содержащийся в pbBuffer, хранится в компактном виде, без заполнения и с обратным порядком байтов. Сериализованный пакет изменений содержит следующие элементы в следующем порядке.

  1. Один раздел заголовка. Раздел заголовка содержит следующие элементы.

    Тип данных

    Длина в байтах

    Описание

    ULONGLONG

    8

    Версия формата сериализации пакета изменений. Данное значение равняется 3, если targetFormatVersion имеет значение SYNC_SERIALIZATION_VERSION_V1, 4, если targetFormatVersion имеет значение SYNC_SERIALIZATION_VERSION_V2, и 5, если targetFormatVersion имеет значение SYNC_SERIALIZATION_VERSION_V3.

  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. Один раздел схемы ключей фильтра источника, если 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

    Сигнатура формата сериализации объекта изменений. Данное значение равняется 5, если параметр targetFormatVersion имеет значение SYNC_SERIALIZATION_VERSION_V1 или SYNC_SERIALIZATION_VERSION_V2, и 6, если targetFormatVersion имеет значение SYNC_SERIALIZATION_VERSION_V3.

    Если идентификаторы реплики имеют фиксированную длину.

    Тип данных

    Длина в байтах

    Описание

    Последовательность байтов

    Длина, указанная в формате идентификатора реплики.

    Идентификатор реплики фиксированной длины.

    Или если идентификаторы реплики имеют переменную длину.

    Тип данных

    Длина в байтах

    Описание

    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