Serialization File Format
This section describes the format used by the serialization to store information. It can be used by tools that need to interpret the file without using the SerializationManager.
Header
All serialization files begin with a general header with generic information.
Name | Bytes | Description |
---|---|---|
Signature | 4 | 'NSDH' The header must be used to discover the endianess of the file (NSDH / HDSN) |
Version | 2 | Version of the file. Last version is 3 |
Unicode | 2 | 0 == String are in ANSI format (1 byte per char), 1 = Srings are stored in UTF-2 format (2 bytes per char) |
NumChunks | 4 | Number of chunks (the next section) |
Chunks
Each chunk is an independent block that it read from beginning to end. Chunks does not share information. This block is repeated for each chunk. The number of chunks is stored in the main header.
Name | Bytes | Description | |
---|---|---|---|
Size | 8 | Size in bytes of this chunk | |
String Size | 8 | Size in bytes of the string list | |
String List | N * sizeof(Char) | A buffer of strings. Each string is separated by a null terminator (0 Ansi) (0 0 UTF-2) | |
Component List Size | 8 | Size in bytes of the component list | |
Component List | N * sizeof(ComponentInfo) | ||
4 | ComponentInfo.classId | An identifier for the component. It is an index to the the string list | |
4 | ComponentInfo.version | The version of the component | |
MetaData Size | 8 | Size in bytes of the metadata block. If 0, there is no metadata stored in the file | |
MetaData Strings Size | 8 | Size in bytes of the metadata string list | |
MetaData String List | N * sizeof(Char) | A buffer of strings. Each string is separated by a null terminator (0 Ansi) (0 0 UTF-2) | |
MetaData Commands Size | 8 | Size in byte of the metadata command buffer | |
MetaData Commands | N | Metadata commands with the format described in the next section | |
Instance List Size | 8 | Size in bytes of the instance list | |
Instance List | N * 4 | Each instance is a 4-byte index to the component list. In version 2 of the file the root is located first in the list. In version 3 of the file the root is located in the last position of the list | |
Data Size | 8 | Size in bytes of the data | |
Data | N | The polymorphic data stored by each component |
Metadata commands
The metadata section describes the information stored in the Data section. The metadata is a list commands. Each command id is a byte followed by the parameters corresponding to that command. if the highest bit of the command id (0x80) is set, the first command is a 4-byte counter indicating that the command is repeated several times.
For example, the ID = 0, is the command BeginInstance. The ID = 0x81 5 is the command BeginInstance repeated 5 times.
////////////////////////////////////////////////////////////////////////////////////////////////////
/// List of commands availables in the metadata (In brackets what is expected to follow after
/// each command, for example [OpenClass] [Desc] [Type] means, after de [OpenClass] command (1byte)
/// a [Desc] (int32) and a [Type] (int32) is expected.
///
/// [Desc] = A NsUInt32 indexing into the metadata strings
////////////////////////////////////////////////////////////////////////////////////////////////////
enum MetaDataCommand
{
// [BeginInstance]
MetaDataCommand_BeginInstance = 0,
// [EndInstance]
MetaDataCommand_EndInstance,
// [BeginGroup] [Desc]
MetaDataCommand_BeginGroup,
// [EndGroup]
MetaDataCommand_EndGroup,
// [BeginArray] [Desc]
MetaDataCommand_BeginArray,
// [EndArray]
MetaDataCommand_EndArray,
// [Command] [Desc]
//@{
MetaDataCommand_Ref,
MetaDataCommand_Int8,
MetaDataCommand_Int16,
MetaDataCommand_Int32,
MetaDataCommand_Int64,
MetaDataCommand_UInt8,
MetaDataCommand_UInt16,
MetaDataCommand_UInt32,
MetaDataCommand_UInt64,
MetaDataCommand_Bool,
MetaDataCommand_Float32,
MetaDataCommand_Float64,
MetaDataCommand_Char8,
MetaDataCommand_Char16,
MetaDataCommand_String8,
MetaDataCommand_String16
//@}
};
Data
Although the data format is free (and can be followed using the metadata) there are some conventions:
- Refs: the references (pointers to other components) are stored as a 4-byte number. That number is an index to the list of instances stored in the chunk. A 0xffffffff (-1) is used to indicate a null pointer.
- Arrays: the first element of the array may be an int32 with the description "size" indicating the number of elements in the array. This element is optional. Each value of the array is stored with the description "val". in dictionaries two values are found, "key" and "val"