ResidualVM logo ResidualVM website - Forums - Contact us BuildBot - Doxygen - Wiki curved edge

This class allows syncing / serializing data (primarily game savestates) between memory and Read/WriteStreams. More...

#include <serializer.h>

Inheritance diagram for Common::Serializer:
Collaboration diagram for Common::Serializer:

List of all members.

Public Types

typedef uint32 Version

Public Member Functions

 Serializer (SeekableReadStream *in, WriteStream *out)
virtual ~Serializer ()
bool isSaving ()
bool isLoading ()
bool err () const
 Returns true if an I/O failure occurred.
void clearErr ()
 Reset the I/O error status as returned by err().
bool syncVersion (Version currentVersion)
 Sync the "version" of the savegame we are loading/creating.
Version getVersion () const
 Return the version of the savestate being serialized.
void setVersion (Version version)
 Manually set the version.
uint bytesSynced () const
 Return the total number of bytes synced so far.
void skip (uint32 size, Version minVersion=0, Version maxVersion=kLastVersion)
 Skip a number of bytes in the data stream.
void syncBytes (byte *buf, uint32 size, Version minVersion=0, Version maxVersion=kLastVersion)
 Sync a block of arbitrary fixed-length data.
bool matchBytes (const char *magic, byte size, Version minVersion=0, Version maxVersion=kLastVersion)
 Sync a 'magic id' of up to 256 bytes, and return whether it matched.
void syncString (String &str, Version minVersion=0, Version maxVersion=kLastVersion)
 Sync a C-string, by treating it as a zero-terminated byte sequence.
template<typename T >
void syncArray (T *arr, size_t entries, void(*serializer)(Serializer &, T &), Version minVersion=0, Version maxVersion=kLastVersion)

Static Public Attributes

static const Version kLastVersion = 0xFFFFFFFF

Protected Attributes

SeekableReadStream_loadStream
WriteStream_saveStream
uint _bytesSynced
Version _version

Detailed Description

This class allows syncing / serializing data (primarily game savestates) between memory and Read/WriteStreams.

It optionally supports versioning the serialized data (client code must use the syncVersion() method for this). This makes it possible to support multiple versions of a savegame format with a single codepath

This class was heavily inspired by the save/load code in the SCUMM engine.

Todo:
Maybe rename this to Synchronizer?
Todo:
One feature the SCUMM code has but that is missing here: Support for syncing arrays of a given type and *fixed* size; and also support for when the array size changed between versions. Also, support for 2D-arrays.
Todo:
Proper error handling!

Definition at line 71 of file serializer.h.


Member Typedef Documentation

Definition at line 73 of file serializer.h.


Constructor & Destructor Documentation

Common::Serializer::Serializer ( SeekableReadStream in,
WriteStream out 
) [inline]

Definition at line 96 of file serializer.h.

virtual Common::Serializer::~Serializer (  )  [inline, virtual]

Definition at line 100 of file serializer.h.


Member Function Documentation

uint Common::Serializer::bytesSynced (  )  const [inline]

Return the total number of bytes synced so far.

Definition at line 173 of file serializer.h.

void Common::Serializer::clearErr (  )  [inline]

Reset the I/O error status as returned by err().

Definition at line 141 of file serializer.h.

bool Common::Serializer::err (  )  const [inline]

Returns true if an I/O failure occurred.

This flag is never cleared automatically. In order to clear it, client code has to call clearErr() explicitly.

Definition at line 131 of file serializer.h.

Version Common::Serializer::getVersion (  )  const [inline]

Return the version of the savestate being serialized.

Useful if the engine needs to perform additional adjustments when loading old savestates.

Definition at line 163 of file serializer.h.

bool Common::Serializer::isLoading (  )  [inline]

Definition at line 103 of file serializer.h.

bool Common::Serializer::isSaving (  )  [inline]

Definition at line 102 of file serializer.h.

bool Common::Serializer::matchBytes ( const char *  magic,
byte  size,
Version  minVersion = 0,
Version  maxVersion = kLastVersion 
) [inline]

Sync a 'magic id' of up to 256 bytes, and return whether it matched.

When saving, this will simply write out the magic id and return true. When loading, this will read the specified number of bytes, compare it to the given magic id and return true on a match, false otherwise.

A typical magic id is a FOURCC like 'MAGI'.

Parameters:
magic magic id as a byte sequence
size length of the magic id in bytes
Returns:
true if the magic id matched, false otherwise

Definition at line 218 of file serializer.h.

void Common::Serializer::setVersion ( Version  version  )  [inline]

Manually set the version.

Definition at line 168 of file serializer.h.

void Common::Serializer::skip ( uint32  size,
Version  minVersion = 0,
Version  maxVersion = kLastVersion 
) [inline]

Skip a number of bytes in the data stream.

This is useful to skip obsolete fields in old savestates.

Definition at line 179 of file serializer.h.

template<typename T >
void Common::Serializer::syncArray ( T *  arr,
size_t  entries,
void(*)(Serializer &, T &)  serializer,
Version  minVersion = 0,
Version  maxVersion = kLastVersion 
) [inline]

Definition at line 259 of file serializer.h.

void Common::Serializer::syncBytes ( byte buf,
uint32  size,
Version  minVersion = 0,
Version  maxVersion = kLastVersion 
) [inline]

Sync a block of arbitrary fixed-length data.

Definition at line 195 of file serializer.h.

void Common::Serializer::syncString ( String str,
Version  minVersion = 0,
Version  maxVersion = kLastVersion 
) [inline]

Sync a C-string, by treating it as a zero-terminated byte sequence.

Todo:
Replace this method with a special Syncer class for Common::String

Definition at line 239 of file serializer.h.

bool Common::Serializer::syncVersion ( Version  currentVersion  )  [inline]

Sync the "version" of the savegame we are loading/creating.

Parameters:
currentVersion current format version, used when writing a new file
Returns:
true if the version of the savestate is not too new.

Definition at line 153 of file serializer.h.


Member Data Documentation

Definition at line 91 of file serializer.h.

Definition at line 88 of file serializer.h.

Definition at line 89 of file serializer.h.

Definition at line 93 of file serializer.h.

const Version Common::Serializer::kLastVersion = 0xFFFFFFFF [static]

Definition at line 74 of file serializer.h.


The documentation for this class was generated from the following file:


Generated on Sat Jan 12 2019 05:04:15 for ResidualVM by doxygen 1.7.1
curved edge   curved edge