Проекты‎ > ‎USDS‎ > ‎USDS 1.0*‎ > ‎

Спецификация бинарных документов USDS

Общая структура документа USDS

Документ USDS 1.0 состоит из следующих блоков:
  • Заголовок документа - содержит сигнатуру USDS, идентификатор и версию словаря;
  • Словарь - описывает схему данных: все используемые теги, их имена, типы данных и связи между ними;
  • Тело документа - сериализованные данные.
Блоки могут отсутствовать в документе, если требуется уменьшить его размер. Возможны следующие комбинации:
  • присутствуют все три блока: данные документы можно редактировать с помощью USDS Editor и преобразовывать в XML / JSON с помощью USDS Convertor. Используйте этот вариант для конфигурационных файлов приложений;
  • только заголовок и словарь: можно передавать однократно при установке сетевого соединения, чтобы впоследствии передавать только тело документа;
  • только заголовок: можно передавать однократно при установке соединения, если клиент сервер уже имеют словарь. Передача заголовка позволяет проконтролировать, что клиент и сервер используют один и тот же словарь, одной и той же версии;
  • только заголовок и тело документа: можно передавать по сети, если оба приложения уже имеют словарь и не используется постоянное соединение. Стороннему наблюдателю будет очень сложно распознать передаваемые данные;
  • только тело документа: можно передавать по сети, если клиент и сервер уже договорились об идентификаторе и версии словаря.

Если в теле документа есть словарь, то обязательно должен присутствовать заголовок.

Бинарная структура документа:

Заголовок

Заголовок USDS 1.0 начинается с сигнатуры '$S' в кодировке ASCII, что соответствует кодам 0x24 0x53. Размер заголовка 10 байт, после сигнатуры следуют:

  • старшая и минорная версии стандарта, для USDS 1.0 это всегда числа 1 и 0;
  • уникальный идентификатор словаря (на схеме 888): целое число 4 байта, Little-endian, значения от 0 до 2147483647;
  • старшая и минорная версии словаря (на схеме 1 и 0): числа от 0 до 255.

Словарь

Словарь начинается с сигнатуры 'D' в кодировке ASCII, что соответствует коду 0x44. Следом за сигнатурой следует:

  • размер зловаря в байтах (Dictionary size), используется тип данных unsigned varint. В размере не учитывается сигнатура (1 байт) и ячейка с самим размером (1+ байт);
  • код кодировки для наименований тегов и комментариев в словаре (Encode): одна из поддерживаемых в USDS кодировок. Используется тип данных varint, полный список кодировок в USDS представлен ниже.
  • описание тегов (Tags description): спиок описаний тегов и комментарии. Описание каждого типа для тегов приведено в нижеследующих разделах.

Общее описание объявления тега:

На рисунке показано:

  • сигнатура тега (Signature), возможны два значения:
    • символ 't' в кодировке ASCII, что соответствует коду 0x74: объявление не корневого тега;
    • символ 'r' в кодировке ASCII, что соответствует коду 0x72: объявление корневого тега (root в текстовом словаре);
  • идентификатор тега (Tag ID): соответствует значению в словаре, от 1 до 2147483647, используется тип данных unsigned varint (1+ байт);
  • размер имени тега в байтах (Name size), используется тип данных unsigned varint (1+ байт);
  • имя тега (Tag name), кодировка указывается при объявлении словаря;
  • тип тега (Tag type): числовой идентификатор одного из типов данных USDS, полный перечень приведен ниже. Используется тип данных unsigned varint (1+ байт);
  • дополнительное описание типа данных (Type description): приведено для каждого типа отдельно в нижеследующих разделах.

Тело документа

Тело документа начинается с сигнатуры 'B' в кодировке ASCII, что соответствует коду 0x42. Следом за сигнатурой следует:

  • сериализованные данные (Serialized Data): каждый блок данных начинается с идентификатора тега за которым следуют сериализованные данные, подробнее смотрите в нижеследующих разделах;
  • признак окончания тела документа - 0. Идентификатор тега не может быть задан в словаре как ноль.

Типы данных

Перечень типов данных USDS:

Перечень поддерживаемых текстовых кодировок для типа данных string и словаря:

Простые типы данных

Теги с простыми типами данных записываются в словарь следующим образом:

На схеме указано:

  • Тип тега (Tag type) - число от 1 до 25, в соответствии с таблицей типов выше.
  • Ограничения (Restrictions): в версии USDS 1.0 для простых типов не поддерживаются, всегда записывается 'n' в кодировке ASCII, что соответствует коду 0x6E.

В тело документа простые теги записываются в следующем виде:

Значение тега (Tag value) имеет размер в соответствии с типом данных, для типов 1-23 этот размер фиксирован и указан в таблице типов.

Типы данных varint и unsigned varint соответствуют спецификации Little Endian Base 128.

Структуры

Теги-структуры записываются в словарь следующим образом:

На схеме указано:
  • тип тега (Tag type) указан как "26", что соответствует идентификатору типа struct;
  • количество полей (Number of fields) в структуре, используется тип данных unsigned varint (1+ байт). В структуре может быть от 1 до 2147483647 полей;
  • идентификаторы полей (Field_N ID): значения от 1 до 2147483647, используется тип данных unsigned varint (1+ байт). Поля следуют в порядке возрастания значения Field ID;
  • размер имени поля (Name size): в байтах, используется тип данных unsigned varint (1+ байт);
  • имена полей (Field_N name): кодировка текста задается при объявлении словаря;
  • типы данных для полей (Field_N type): один из типов USDS, кроме struct. Если в качестве типа необходимо указать другой тег, то устанавливается в 0, и следующим байтом задается идентификатор любого другого тега. Если в качетсве ID тега указан ID самой структуры, то данное поле должно быть опциональным. Используется тип данных unsigned varint (1+ байт);
  • ограничения для полей:
    • признак обязательного поля: символ 'r' в кодировке ASCII, что соответствует коду 0x72. В текстовой версии словаря нет ключевого слова "default";
    • признак опционального поля: символ 'o' в кодировке ASCII, что соответствует коду 0x6F. В текстовом словаре объявляется как "default NULL". Опциональным может быть любое поле, в том числе все поля структуры;
    • признак поля со значением по умолчанию: символ 'd' в кодировке ASCII, что соответствует коду 0x64. В текстовом словаре объявляется как "default _значение_". Значение по умолчанию может быть только у простых типов и у строк. Само значение по умолчанию (Default value) заносится сразу после признака.

В тело документа структуры записываются следующим образом:

На схеме указано:

  • блок данных начинается с идентификатора тега структуры (Tag ID);
  • в первую очередь следуют значения обязательных полей (в текстовом словаре не указано "dafault"), они перечисляются в порядке возрастания идентификаторов полей (Field_N ID). Сам идентификатор не указывается для экономии места;
  • далее следуют не обязательные поля (default value, default NULL), они следуют в порядке возрастания идентификаторов полей (Field_N ID). Указывается сам идентификатор поля, и за ним следует значение поля. Не обязательные поля не записываются в тело документа, если:
    • поле объявлено как "default value", и его значение сейчас соответствует дефолтному (Field 3);
    • поле объявлено как "default NULL" и оно сейчас отсутствует (Field 2 и 6);
  • блок данных завершается байтом 0x00, но завершающий нулевой блок отсутствует, если:
    • при объявлении структуры в словаре не указали ни одного опционального и дефолтного поля: в этом случае размер структуры известен и нет необходимости завершать блок данных нулем;
    • в структуре (в теле документа) присутствует поле с максимальным значением идентификатора опционального поля (Field ID). Например, было объявлено, что поля с ID 2, 3, 4 и 6 опциональные или дефолтные. Если поле 6 было записано в тело документа, то очевидно, что это окончание структуры, и завершающий нулевой блок не требуется.

Массивы

Теги-массивы записываются в словарь следующим образом:

На схеме указано:

  • тип тега (Tag type) указан как "27", что соответствует идентификатору типа array;
  • размер массива (Array size): количество элементов в массиве. Если указано 0, то размер массива плавающий - записывается в теле документа. Используется тип данных unsigned varint (1+ байт);
  • тип данных для элементов массива (Type for array) и соответствующие описания типов.

В тело документа массивы записываются следующим образом:

На схеме указано:

  • иденитфикатор тега-массива (Tag ID);
  • размер массива (Array size) - количество элементов массива. Указывается только если размер массива не зафиксиован в словаре. Используется тип данных unsigned varint (1+ байт);
  • значения элементов массива.

Строки

Теги-строки записываются в словарь следующим образом:

На схеме указано:

  • тип тега (Tag type) указан как "28", что соответствует идентификатору типа string;
  • кодировка строки (Encode): идентификатор. Если указано 0, то кодировка записывается в теле документа для каждой строки. Используется тип данных unsigned varint (1+ байт);
  • ограничения на размер строки (Restrictions):
    • без ограничений: 'n' в кодировке ASCII, что соответствует коду 0x6E. В тело документа всегда записывается размре строки (количество символов);
    • ограничен максимальный размер строки: 'm' в кодировке ASCII, что соответствует коду 0x6D. Далее следует количество символов, используется тип данных unsigned varint (1+ байт).  В тело документа всегда записывается размре строки (количество символов);
    • размер строки фискирован: 'f' в кодировке ASCII, что соответствует коду 0x66. Далее следует количество символов, используется тип данных unsigned varint (1+ байт). В тело документа не записывается размре строки.
В тело документа строки записываются следующим образом:

Списки

Теги-списки записываются в словарь следующим образом:

На схеме указано:

  • тип тега (Tag type) указан как "29", что соответствует идентификатору типа list;
  • ограничения (List restrictions): в версии USDS 1.0 для списков не поддерживаются, всегда записывается 'n' в кодировке ASCII, что соответствует коду 0x6E;
  • тип данных для элементов списка (Type for list) и соответствующие описания типов.
Размер списка (количество элементов) всегда записывается в тело документа в формате распределенного unsigned varint:

В первую группу значений (values) входит не более 127 элементов списка, во вторую не более 16 256, в третью не более 2 080 768 и т.д.

Полное количество элемнетов списка определяется по обычным правилам преобразования unsigned varint.

Ассоциативные массивы (Map)

Теги-карты записываются в словарь следующим образом:

На схеме указано:

  • тип тега (Tag type) указан как "30", что соответствует идентификатору типа map;
  • ограничения (Map restrictions): в версии USDS 1.0 для карт не поддерживаются, всегда записывается 'n' в кодировке ASCII, что соответствует коду 0x6E;
  • тип данных для ключей (Type for key) и соответствующие описания типов;
  • тип данных для значений (Type for value) и соответствующие описания типов.
Размер ассоциативного массива (количество пар элементов) всегда записывается в тело документа в формате распределенного unsigned varint:

В первую группу значений (values) входит не более 127 элементов списка, во вторую не более 16 256, в третью не более 2 080 768 и т.д.

Полное количество элемнетов списка определяется по обычным правилам преобразования unsigned varint.

Полиморфы

Теги-полиморфы записываются в словарь следующим образом:

На схеме указано:

  • тег-полиморф не может быть корневым;
  • тип тега (Tag type) указан как "31", что соответствует идентификатору типа polymorph;
  • количество элементов полиморфа (Number of elements): количество тегов. Используется тип данных unsigned varint (1+ байт);
  • список тегов, в качестве которых может представляться полиморф, с любым типом данных, кроме других полиморфов. Спиоск должен быть уникальным, теги следуют в порядке нарастания Tag ID. Элементом полиморфа не может быть сам полиморф (рекурсия запрещена).
В тело документа полиморфы записываются следующим образом:

В качестве значения тега "Tag ID = 11"  в тело документа записывается не 10 тег (другой полиморф), а сразу итоговый тег 15.


2015.08.10, Андрей Абрамов
CC BY 4.0

Comments

Не удалось найти URL спецификации гаджета