Introduction

The iser library provides a comprehensive serialization framework for persisting and loading objects. It supports multiple archive formats including binary, XML, and compact XML, with automatic version handling and type identification.

Key Features

Archive-Based Serialization: Read and write archives with consistent interface
Multiple Formats: Binary, XML, and compact XML archive support
Version Management: Automatic version tracking and compatibility checking
Type Safety: Object type identification and validation
Memory and File: Support for both memory-based and file-based archives
Compression: Optional bit-level compression for compact storage

Architecture

The iser library is organized into several key components:

Archive Types

iser::CMemoryWriteArchive: Write to memory buffer
iser::CMemoryReadArchive: Read from memory buffer
iser::CFileWriteArchive: Write to file
iser::CFileReadArchive: Read from file
iser::CBitMemoryWriteArchive: Bit-level compressed memory writing
iser::CCompactXmlMemWriteArchive: Compact XML format writing

Core Interfaces

iser::ISerializable: Interface for serializable objects
iser::IReadArchive: Interface for reading archives
iser::IWriteArchive: Interface for writing archives
iser::IObject: Extended serializable interface with type information
iser::IVersionInfo: Version information for compatibility

Utilities

iser::CArchiveHeaderInfo: Archive header metadata
iser::CArchiveTag: Tagged data sections in archives
iser::CVersionInfo: Version information implementation

Usage Examples

Writing to Archive

#include <iser/CMemoryWriteArchive.h>
#include <iser/ISerializable.h>
 
class MyData : public iser::ISerializable
{
public:
    virtual void Serialize(iser::IArchive& archive) override
    {
        archive.Process(m_value, "value");
        archive.Process(m_name, "name");
    }
    
private:
    int m_value = 42;
    QString m_name = "Example";
};
 
// Write to memory
iser::CMemoryWriteArchive writeArchive;
MyData data;
data.Serialize(writeArchive);
 
// Get serialized data
QByteArray serialized = writeArchive.GetData();

Reading from Archive

#include <iser/CMemoryReadArchive.h>
 
// Read from memory
iser::CMemoryReadArchive readArchive(serialized);
MyData loadedData;
loadedData.Serialize(readArchive);
 
// Data is now restored

File-Based Serialization

#include <iser/CFileWriteArchive.h>
#include <iser/CFileReadArchive.h>
 
// Write to file
iser::CFileWriteArchive fileWrite("data.bin");
data.Serialize(fileWrite);
 
// Read from file
iser::CFileReadArchive fileRead("data.bin");
MyData loadedFromFile;
loadedFromFile.Serialize(fileRead);

Version Management

#include <iser/CVersionInfo.h>
#include <iser/CMemoryWriteArchive.h>
 
// Create version info
iser::CVersionInfo versionInfo(1, 2, 0);
 
// Create archive with version
iser::CMemoryWriteArchive archive(&versionInfo);
 
// When reading, version is automatically checked
iser::CMemoryReadArchive readArchive(archive.GetData());
const iser::IVersionInfo* loadedVersion = readArchive.GetVersionInfo();

Tagged Sections

#include <iser/CArchiveTag.h>
 
// Write with tags
iser::CMemoryWriteArchive archive;
{
    iser::CArchiveTag tag(archive, "Header");
    archive.Process(headerData, "data");
}
{
    iser::CArchiveTag tag(archive, "Body");
    archive.Process(bodyData, "data");
}

Thread Safety

Archive objects are not thread-safe. Each thread should use its own archive instance.

Dependencies

The iser library depends on:

istd: Standard utilities and interfaces
Qt Core: QString, QByteArray, QIODevice, and other core classes

Best Practices

Implement ISerializable: All persistent objects should implement ISerializable
Use Named Fields: Always provide field names for better debugging and XML output
Version Control: Include version information for data compatibility
Handle Errors: Check archive state after serialization operations
Symmetric Operations: Ensure Serialize() works for both reading and writing
Use Tags: Organize complex data structures with CArchiveTag
Test Compatibility: Test serialization with different versions