Main DescriptionThe binary document USDS 1.0 consists of the following parts: - Head: contains USDS signature, an identifier and a version of the dictionary;
- Dictionary: contains tag's description (names, types, relationship);
- Body: contains serialized data.
These parts can be absent: - All parts are represented in a binary document: you can edit the data using USDS Editor, convert the data to XML and JSON using USDS Converter. Use this variant for configuration files and debugging;
- The head and dictionary presented: use this for establishing a connection between client and server;
- The Head only: use this for establishing a connection if client and server have dictionary already;
- The head and body: transfer this objects if client and server have dictionary already and you don't need stable connection;
- The body only: transfer this objects if connection established already.
If binary document includes dictionary then head mast be included too. The main description of USDS binary document:
Head
The head of USDS 1.0 start from signature '$S' (ASCII, 0x24 0x53), it's size is 10 bytes. After signature are following: - Major and minor USDS version: numbers 1 and 0 for USDS 1.0;
- Integer identifier of the dictionary: 4 bytes, little-endian, from 0 to 2147483647;
- Major and minor dictionary version: numbers from 0 to 255.
Dictionary
The dictionary starts from signature 'D' (ASCII, 0x44). After signature are following: - The dictionary size in bytes, unsigned varint. The size includes all bytes after itself;
- Encode for tag names and comments in the dictionary: unsigned varint, one of supported in USDS, the list represented below;
- Tag's description: names, types, relationship.
The main description of a tag: The scheme contains: - signature:
- 't' (ASCII, 0x74): not root tag;
- 'r' (ASCII, 0x72): root tag;
- Tag identifier (from the text dictionary): unsigned varint, from 1 to 2147483647;
- The size of tag name: the number of bytes, unsigned varint;
- Tag name;
- The integer identifier of tag's type: the list of all types represented below;
- Type description: it's specific for every type.
Body
The body starts from signature 'B' (ASCII, 0x42). After signature are following: - Serialized data: every block of data starts from tag identifier, formats are represented below;
- The signature of the end of the document: 0 (zero, Tag ID can't be zero).
Data typesThe list of USDS data types:
The gadget spec URL could not be found The list of supported text encodes for the dictionary an strings:
The gadget spec URL could not be found Simple typesThe main description of simple types: The scheme contains: - The identifier of tag type (1-25), unsigned varint;
- Type restrictions: not supported in USDS 1.0, always 'n' (ASCII, 0x6E).
Simple type in the body:
The type 1-23 have fixed size. The types varint and unsigned varint correspond to Little Endian Base 128. Structure
The main description of structures: The scheme contains: - Tag type: 26 for structures;
- Number of fields: unsigned varint, from 1 to 2147483647;
- Field identifiers: unsigned varint, from 1 to 2147483647;
- The size of field name: in symbols, unsigned varint;
- Field names;
- Field type:
- any USDS type instead "struct';
- the name of the other tag with any type;
- the name of this tag, but the field must be optional;
- Field restrictions:
- required field: 'r' (ASCII, 0x72);
- optional filed: 'o' (ASCII, 0x6F), "default NULL" in text dictionary. Parser will return NULL, if the body doesn't contain this field;
- fields with default value: 'd' (ASCII, 0x64), the body doesn't contain this field if it's equal to default value.
The structure in the body: The scheme contains: - Tag identifier, unsigned varint;
- All required fields in ascending order of filed ID (1 and 5);
- All other fields in ascending order of filed ID, excepting:
- the fields with default value, if it's equal default value (3);
- optional fields, if it's equal NULL (2 and 6);
- The structure ends with 0 (zero), but this final byte can be excepted if:
- the structure has only required fields;
- the last field (with maximum field ID) is in the body.
ArraysThe main description of arrays: The scheme contains: - Tag type: 27 for arrays;
- Array size: the number of elements, unsigned varint. The value 0 are used for unfixed size;
- Type for array: simple types, strings or other tag name.
The array in the body: The scheme contains: - Tag identifiers: unsigned varint;
- Array size: amount of the elements, unsigned varint. It absents if size is set in dictionary;
- Element values.
StringsThe main description of strings: The scheme contains: - Tag type: 28 for strings;
- Text encode: unsigned varint, one of supported in USDS, or 0 if unfixed;
- Restrictions:
- no restrictions: 'n' (ASCII, 0x6E);
- limited size: 'm' (ASCII, 0x6D);
- fixed size: 'f' (ASCII, 0x66).
The strings in the body: ListThe main description of lists: The scheme contains: - Tag type: 29 for lists, unsigned varint;
- List restrictions: not supported in USDS 1.0 - 'n' (ASCII, 0x6E);
- Type for list elements: simple type, string or other tag name, unsigned varint.
The lists in the body: The scheme contains: - Tag identifiers: unsigned varint;
- List values;
- List size: the number of elements, distributed unsigned varint:
Maps
The main description of maps: The scheme contains: - Tag type: 30 for maps, unsigned varint;
- Map restrictions: not supported in USDS 1.0 - 'n' (ASCII, 0x6E);
- Type for keys: simple type, string or other tag name, unsigned varint;
- Type for values: simple type, string or other tag name, unsigned varint.
The maps in the body: The scheme contains: - Tag identifiers: unsigned varint;
- Map keys and values;
- Map size: the number of couples, distributed unsigned varint:
PolymorphThe main description of polymorph:  The scheme contains: - Polymorph tag can't be "root";
- Tag type: 31 for polymorph, unsigned varint;
- Number of elements: unsigned varint;
- List of the tags: any tag types, unsigned varint.
The polymorph in the body: There is no tag "10" in the polymorph "11", instead it used tag 15 directly. 2015.08.12, Andrey Abramov
CommentsThe gadget spec URL could not be found |