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

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.

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

  • 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, возвращается SYNC_E_INVALID_VERSION. Например, набор знаний, возвращаемый ISyncKnowledge2::ProjectOntoColumnSet, содержит элементы, введенные в Sync Framework 2.0, и поэтому не может быть сериализован с использованием значения SYNC_SERIALIZATION_VERSION_V1, указанного для targetFormatVersion.

NoteПримечание.

Сериализация в формате 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

    Подпись вектора синхронизации. Это значение равно 9, если вектор синхронизации содержит элементы канала FeedSync, и равно 1 в противном случае.

    ULONG

    4

    Число элементов, содержащихся в этом векторе синхронизации.

    Если вектор синхронизации содержит элементы канала FeedSync, то в сериализованных данных набора знаний существует следующий раздел; в противном случае он не существует.

    Тип данных Длина в байтах Описание

    ULONG

    4

    Число обновлений, внесенных в канал FeedSync, сопоставленный с этим набором знаний. Это значение соответствует атрибуту updates канала FeedSync.

    BYTE

    1

    Указывает, выполняет ли канал FeedSync отслеживание конфликтов. Это значение соответствует атрибуту noconflicts канала FeedSync. Это значение равно 1, если задан параметр noconflicts, и равно 0 в противном случае.

    В остальной части вектора синхронизации содержится список элементов вектора синхронизации, где число элементов равно значению, ранее указанному в разделе вектора синхронизации.

    Каждый элемент вектора синхронизации содержит следующие элементы:

    Тип данных Длина в байтах Описание

    ULONG

    4

    Ключ реплики.

    ULONGLONG

    8

    Счетчик тактов.

    Если набор знаний сопоставлен с каналом FeedSync, то каждый элемент вектора синхронизации содержит следующие дополнительные элементы:

    Тип данных Длина в байтах Описание

    ULONG

    4

    Часть значения when канала FeedSync, содержащая дату.

    ULONG

    4

    Часть значения when канала FeedSync, содержащая время.

    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