ezEngine  Milestone 7
ezArchiveReader Class Reference

A chunk stream reader that supports restoring reflected objects and pointer references. More...

#include <Archive.h>

Inheritance diagram for ezArchiveReader:

Classes

struct  ObjectMapping
 
struct  ObjectRef
 
struct  RttiData
 The RTTI data that is stored in the archive. More...
 

Public Member Functions

 ezArchiveReader (ezStreamReaderBase &stream)
 The constructor takes another stream to which all read requests are passed along.
 
 ~ezArchiveReader ()
 Destructor.
 
void SetLogInterface (ezLogInterface *pLog)
 The archive will output status information, warnings and errors through the given interface.
 
virtual void BeginStream () override
 Starts reading from the stream. More...
 
virtual void EndStream () override
 Finishes reading from the archive. This must be called once no more data should be read. More...
 
const ezDynamicArray< RttiData > & GetArchiveRttiData () const
 Returns the RTTI data that was stored in the archive. This information is available right after the call to BeginStream()
 
ezUInt32 ReadObjectReference (void **ppReference)
 Reads a reference to an object. The reference will be patched up once the information is available. More...
 
void SetObjectReferenceMapping (ezUInt32 uiObjectID, void *pNewObject)
 Associates the given new pointer with a reference ID. All references read through ReadObjectReference() that return the given object ID will be patched up with the given pointer when archive reading is finished.
 
void * GetObjectReferenceMapping (ezUInt32 uiObjectID) const
 Returns the pointer value that is associated with the given object ID.
 
void * ReadTypedObject (const ezRTTI **out_pRtti=nullptr, ezUInt16 *out_pTypeID=nullptr)
 Reads the RTTI information about a typed object and creates an object of that type. The instance is then returned. More...
 
ezReflectedClassReadReflectedObject ()
 Restores an object that was written with ezArchiveWriter::WriteReflectedObject(). More...
 
void RegisterTypeSerializer (const ezRTTI *pRttiBase, ezArchiveSerializer *pSerializer)
 Registers an ezArchiveSerializer to use for specific object types (and all derived classes). More...
 
const ezDeque
< ezReflectedClass * > & 
GetDeserializedObjects () const
 Returns an array with pointers to all objects that were read using ReadReflectedObject().
 
void CallOnDeserialized ()
 Calls ezReflectedClass::OnDeserialized() on all objects that were read with ReadReflectedObject().
 
ezUInt32 GetStoredTypeVersion (const ezRTTI *pRtti) const
 Returns the version with which objects of the given type were written to the archive. More...
 
template<typename TYPE >
ezUInt32 GetStoredTypeVersion () const
 Returns the version with which objects of the given type were written to the archive. More...
 
- Public Member Functions inherited from ezChunkStreamReader
 ezChunkStreamReader (ezStreamReaderBase &stream)
 Pass the underlying stream writer to the constructor.
 
virtual ezUInt64 ReadBytes (void *pReadBuffer, ezUInt64 uiBytesToRead) override
 Reads bytes directly from the stream. Only allowed while a valid chunk is available. Returns 0 bytes when the end of a chunk is reached, even if there are more chunks to come.
 
void SetEndChunkFileMode (EndChunkFileMode mode)
 
const ChunkInfoGetCurrentChunk () const
 Returns information about the current chunk.
 
void NextChunk ()
 Skips the rest of the current chunk and starts reading the next chunk.
 
- Public Member Functions inherited from ezStreamReaderBase
 ezStreamReaderBase ()
 Constructor.
 
virtual ~ezStreamReaderBase ()
 Virtual destructor to ensure correct cleanup.
 
template<typename T >
ezResult ReadWordValue (T *pWordValue)
 Helper method to read a word value correctly (copes with potentially different endianess)
 
template<typename T >
ezResult ReadDWordValue (T *pDWordValue)
 Helper method to read a dword value correctly (copes with potentially different endianess)
 
template<typename T >
ezResult ReadQWordValue (T *pQWordValue)
 Helper method to read a qword value correctly (copes with potentially different endianess)
 
virtual ezUInt64 SkipBytes (ezUInt64 uiBytesToSkip)
 Helper method to skip a number of bytes (implementations of the stream reader may implement this more efficiently for example)
 

Private Member Functions

void FinishReferenceMapping ()
 
void SetObjectReferenceMapping (ezUInt32 uiObjectID, void *pNewObject, ezUInt32 uiDataSize)
 
ezArchiveSerializerGetTypeSerializer (const ezRTTI *pRttiBase)
 

Private Attributes

bool m_bStreamFinished
 
ezLogInterfacem_pLog
 
ezMap< const ezRTTI
*, ezArchiveSerializer * > 
m_TypeSerializers
 
ezDynamicArray< ObjectRefm_ObjectIDtoPointer
 
ezDeque< ObjectMappingm_ObjectsToMap
 
ezDynamicArray< RttiDatam_Types
 
ezStreamReaderBasem_InputStream
 
ezDeque< ezReflectedClass * > m_DeserializedReflected
 
ezMap< const ezRTTI *, ezUInt32 > m_StoredVersion
 

Additional Inherited Members

- Public Types inherited from ezChunkStreamReader
enum  EndChunkFileMode { SkipToEnd, JustClose }
 

Detailed Description

A chunk stream reader that supports restoring reflected objects and pointer references.

See ezArchiveWriter for more details.


Class Documentation

struct ezArchiveReader::RttiData

The RTTI data that is stored in the archive.

Class Members
const ezRTTI * m_pRTTI The live ezRTTI object with the same type name. If the type in the archive is unknown, this will be nullptr.
ezString m_sTypeName The name of the RTTI type.
ezUInt32 m_uiObjectCount How many objects of this type are stored in the archive in total.
ezUInt32 m_uiTypeVersion The version with which objects of this type were written to the archive.

Member Function Documentation

void ezArchiveReader::BeginStream ( )
overridevirtual

Starts reading from the stream.

After this call the RTTI information from the archive is available.

Reimplemented from ezChunkStreamReader.

void ezArchiveReader::EndStream ( )
overridevirtual

Finishes reading from the archive. This must be called once no more data should be read.

All pointer-mappings for inter-object references are resolved at this time. Object references that were read previously and could not be resolved at that time will be patched up here. Therefore all pointers given to ReadObjectReference() must stay valid till after this call so that they can be written to.

Reimplemented from ezChunkStreamReader.

ezUInt32 ezArchiveReader::GetStoredTypeVersion ( const ezRTTI pRtti) const

Returns the version with which objects of the given type were written to the archive.

This is very important during deserialization, so that objects know how to interpret the data in the stream. Always call this in ezReflectedClass::Deserialize() with the own type.

template<typename TYPE >
ezUInt32 ezArchiveReader::GetStoredTypeVersion ( ) const
inline

Returns the version with which objects of the given type were written to the archive.

This is very important during deserialization, so that objects know how to interpret the data in the stream. Always call this in ezReflectedClass::Deserialize() with the own type.

ezUInt32 ezArchiveReader::ReadObjectReference ( void **  ppReference)

Reads a reference to an object. The reference will be patched up once the information is available.

This function reads a pointer to an object and stores it in the pointer whose address is given (therefore the parameter is a pointer to a pointer). However, many references will not be available at the time the reference is supposed to be read. Therefore the given pointer is stored and will be patched when EndStream() is called. A reference that cannot be patched, because the referenced object is never restored, will be set to nullptr.

This function always returns an integer token for the requested reference. This can be used to set up the mapping manually via SetObjectReferenceMapping(). This might be necessary if you want to restore custom pointer references.

ezReflectedClass * ezArchiveReader::ReadReflectedObject ( )

Restores an object that was written with ezArchiveWriter::WriteReflectedObject().

This internally calls ReadTypedObject(). If an object cannot be created due to an unknown type, it will be skipped. Once the object is created, ezReflectedClass::Deserialize() is called on it. It is also stored in the referenced objects map, so references to this instance can be restored. Additionally the instance is queued for the ezReflectedClass::OnDeserialized() callback. Once the entire archive has been read, you should call CallOnDeserialized(), so that all objects read through ReadReflectedObject() can do post deserialization work.

void * ezArchiveReader::ReadTypedObject ( const ezRTTI **  out_pRtti = nullptr,
ezUInt16 *  out_pTypeID = nullptr 
)

Reads the RTTI information about a typed object and creates an object of that type. The instance is then returned.

You need to use this function for objects that were written with ezArchiveWriter::BeginTypedObject(). Will return nullptr, if the stored type cannot be created because the type is unknown or no allocator / serializer is available.

The parameter out_pRtti optionally returns the RTTI information about the instance. If the type in the archive is unknown at runtime, this will be nullptr. The parameter out_pTypeID will return the internal type index. Use GetArchiveRttiData() to get more information about the type. This allows to at least know the type name of an object that failed to be created.

void ezArchiveReader::RegisterTypeSerializer ( const ezRTTI pRttiBase,
ezArchiveSerializer pSerializer 
)

Registers an ezArchiveSerializer to use for specific object types (and all derived classes).

All serializers must be registered before the archive is read from. Every time a typed / reflected object is read, it is checked whether there is a serializer for this object type (or any of its base classes). If so, that serializer is called to read additional data from the stream, before the object itself is deserialized.

See Also
ezArchiveWriter::RegisterTypeSerializer()

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