Zen API

- Home
- Topics
- Types
- Files

All Classes Files Functions Variables Typedefs Friends Macros Modules Pages
Public Member Functions | Related
kSerializer Class Reference
kApi/Io

## Description

Base class for serialization/deserialization classes.

The kDat5Serializer and kDat6Serializer classes extend the kSerializer base class to implement the kdat5 and kdat6 binary serialization formats, respectively. These formats represent binary serialization schemes developed for and used extensively with the Zen API, providing a simple method to serialize/deserialize complete object graphs. The primary difference between these formats is that kdat6 can be easily extended to serialize types defined in other assemblies. kdat6 is recommended for object serialization when legacy compatibilty is not a concern.

kSerializer itself is also an instantiable class. The kSerializer base class does not provide the ability to automatically serialize/deserialize complete objects, but can be used to read/write primitive data and arrays. This approach can be used to implement custom binary serialization schemes without needing to extend the kSerializer class.

kSerializer provides an internal write buffer, but does not provide a read buffer. Accordingly, for best performance, the underlying stream should provide a read buffer, but not a write buffer. (For kTcpClient, a socket-level write buffer is helpful, but a client-level write buffer should be avoided.) kSerializer does not automatically flush its internal write buffer when the serializer is destroyed. The Flush method must be used to ensure that all bytes are written to the underlying stream.

By default, kSerializer assumes that primitive values should be encoded to (or decoded from) little endian format. Accordingly, on big endian platforms, the in-memory byte ordering will be swapped as data is read from or written to the underlying stream. For custom parser/formatters or in derived serialization classes, this default behaviour can be overriden using the kSerializer_SetEndianness method.

By default, kSerializer assumes that kSize values should be encoded/decoded as 32-bit values. For custom parser/formatters or in derived serialization classes, this default behaviour can be overriden using the kSerializer_SetSizeEncoding method.

The following example illustrates three different approaches for writing an image object in kdat-6 format.

//This approach provides the most control/flexibility.
kStatus WriteObject1(kImage image, const kChar* path)
{
kFile file = kNULL;
kSerializer writer = kNULL;
kTry
{
//open a file for writing; do not allocate a write buffer (serializers have built-in write buffers)
kTest(kFile_Construct(&file, path, kFILE_MODE_WRITE, kNULL));
//construct a kDat6Serializer object (a kSerializer subclass that implements kdat6 format)
kTest(kDat6Serializer_Construct(&writer, file, kNULL));
//serialize the image to file; it's possible to write multiple objects here, but we only need to write one
kTest(kSerializer_WriteObject(writer, image));
//serializers must always be flushed before closing; otherwise, data may be lost
kTest(kSerializer_Flush(writer));
}
kFinally
{
kObject_Destroy(writer);
kObject_Destroy(file);
kEndFinally();
}
return kOK;
}
//This approach uses a kSerializer utility function to simplify the operation above. This approach is limited
//to writing a single object to file, but that's all we need here.
kStatus WriteObject2(kImage image, const kChar* path)
{
return kSerializer_SaveObject(image, kTypeOf(kDat6Serializer), path);
}
//This approach uses a kUtils function to save on typing.
kStatus WriteObject3(kImage image, const kChar* path)
{
return kSave6(image, path);
}

The following example illustrates the implemenation of a custom binary parser, using the kSerializer base class directly.

#include <kApi/Io/kSerializer.h>
#define MY_DATA_CAPACITY (128)
typedef struct MyData
{
k32u id;
kText64 name;
kSize valueCount;
k64u values[MY_DATA_CAPACITY];
} MyData;
kStatus ReadData(kStream stream, MyData* data)
{
kSerializer reader = kNULL;
kTry
{
//construct a plain serializer object (can write/write primitive types and arrays)
kTest(kSerializer_Construct(&reader, stream, kNULL, kNULL));
//read the data id/name
kTest(kSerializer_Read32u(reader, &data->id));
kTest(kSerializer_ReadText(reader, data->name, kCountOf(data->name)));
//read data content, encoded as a variable-length array of 64-bit values
kTest(kSerializer_ReadSize(reader, &data->valueCount));
kTestTrue(data->valueCount <= kCountOf(data->values), kERROR_FORMAT);
kTest(kSerializer_Read64uArray(reader, data->values, data->valueCount));
}
kFinally
{
kObject_Destroy(reader);
kEndFinally();
}
return kOK;
}
Inheritance diagram for kSerializer:

## Public Member Functions
kStatus | kSerializer_AdvanceRead (kSerializer serializer, kSize offset)
| Reads and discards a specified number of bytes. More...
kStatus | kSerializer_BeginRead (kSerializer serializer, kType sizeType, kBool includeSize)
| Begins reading a measured data section. More...
kStatus | kSerializer_BeginWrite (kSerializer serializer, kType sizeType, kBool includeSize)
| Begins writing a measured section of data, using an 8, 16, 32, or 64-bit integer to record the size. More...
kBool | kSerializer_CanWriteType (kSerializer serializer, kType type)
| Determines whether this serializer can write the specified object type. More...
kStatus | kSerializer_Construct (kSerializer *serializer, kStream stream, kType serializerType, kAlloc allocator)
| Constructs a serializer object using the specified serialization format. More...
kEndianness | kSerializer_Endianness (kSerializer serializer)
| Reports the (byte ordering) of encoded/decoded values. More...
kStatus | kSerializer_EndRead (kSerializer serializer)
| Ends reading a measured data section. More...
kStatus | kSerializer_EndWrite (kSerializer serializer)
| Ends writing a measured data section. More...
kStatus | kSerializer_Flush (kSerializer serializer)
| Flushes the serializer write buffer to the underlying stream. More...
kBool | kSerializer_IsMemoryCompatible (kSerializer serializer, kType type)
| Determines whether a value type is memory-compatible with the serializer. More...
kStatus | kSerializer_LoadObject (kObject *object, kType serializerType, const kChar *filePath, kAlloc readAlloc)
| Loads an object from file using the specified serializer type. More...
kStatus | kSerializer_Read16s (kSerializer serializer, k16s *data)
| Reads a k16s value. More...
kStatus | kSerializer_Read16sArray (kSerializer serializer, k16s *data, kSize count)
| Reads a k16s array. More...
kStatus | kSerializer_Read16u (kSerializer serializer, k16u *data)
| Reads a k16u value. More...
kStatus | kSerializer_Read16uArray (kSerializer serializer, k16u *data, kSize count)
| Reads a k16u array. More...
kStatus | kSerializer_Read32f (kSerializer serializer, k32f *data)
| Reads a k32f value. More...
kStatus | kSerializer_Read32fArray (kSerializer serializer, k32f *data, kSize count)
| Reads a k32f array. More...
kStatus | kSerializer_Read32s (kSerializer serializer, k32s *data)
| Reads a k32s value. More...
kStatus | kSerializer_Read32sArray (kSerializer serializer, k32s *data, kSize count)
| Reads a k32s array. More...
kStatus | kSerializer_Read32u (kSerializer serializer, k32u *data)
| Reads a k32u value. More...
kStatus | kSerializer_Read32uArray (kSerializer serializer, k32u *data, kSize count)
| Reads a k32u array. More...
kStatus | kSerializer_Read64f (kSerializer serializer, k64f *data)
| Reads a k64f value. More...
kStatus | kSerializer_Read64fArray (kSerializer serializer, k64f *data, kSize count)
| Reads a k64f array. More...
kStatus | kSerializer_Read64s (kSerializer serializer, k64s *data)
| Reads a k64s value. More...
kStatus | kSerializer_Read64sArray (kSerializer serializer, k64s *data, kSize count)
| Reads a k64s array. More...
kStatus | kSerializer_Read64u (kSerializer serializer, k64u *data)
| Reads a k64u value. More...
kStatus | kSerializer_Read64uArray (kSerializer serializer, k64u *data, kSize count)
| Reads a k64u array. More...
kStatus | kSerializer_Read8s (kSerializer serializer, k8s *data)
| Reads a k8s value. More...
kStatus | kSerializer_Read8sArray (kSerializer serializer, k8s *data, kSize count)
| Reads a k8s array. More...
kStatus | kSerializer_Read8u (kSerializer serializer, k8u *data)
| Reads a k8u value. More...
kStatus | kSerializer_Read8uArray (kSerializer serializer, k8u *data, kSize count)
| Reads a k8u array. More...
kStatus | kSerializer_ReadByte (kSerializer serializer, kByte *data)
| Reads a kByte value. More...
kStatus | kSerializer_ReadByteArray (kSerializer serializer, void *data, kSize count)
| Reads a kByte array. More...
kStatus | kSerializer_ReadChar (kSerializer serializer, kChar *data)
| Reads a kChar value. More...
kStatus | kSerializer_ReadCharArray (kSerializer serializer, kChar *data, kSize count)
| Reads a kChar array. More...
kBool | kSerializer_ReadCompleted (kSerializer serializer)
| Determines whether the current measured read section has more bytes. More...
kStatus | kSerializer_ReadItems (kSerializer serializer, kType type, kTypeVersion version, void *items, kSize count)
| Reads an array of values or objects. More...
kStatus | kSerializer_ReadObject (kSerializer serializer, kObject *object, kAlloc allocator)
| Reads an object from the underlying stream. More...
kStatus | kSerializer_ReadSize (kSerializer serializer, kSize *data)
| Reads a kSize value. More...
kStatus | kSerializer_ReadSizeArray (kSerializer serializer, kSize *data, kSize count)
| Reads a kSize array. More...
kStatus | kSerializer_ReadSSize (kSerializer serializer, kSSize *data)
| Reads a kSSize value. More...
kStatus | kSerializer_ReadSSizeArray (kSerializer serializer, kSSize *data, kSize count)
| Reads a kSSize array. More...
kStatus | kSerializer_ReadText (kSerializer serializer, kChar *data, kSize capacity)
| Reads a null-terminated kChar array. More...
kStatus | kSerializer_ReadType (kSerializer serializer, kType *type, kTypeVersion *version)
| Reads a type code. More...
kStatus | kSerializer_Reset (kSerializer serializer)
| Discards any streaming context accumulated by the serializer. More...
kStatus | kSerializer_SaveObject (kObject object, kType serializerType, const kChar *filePath)
| Saves an object to file using the specified serializer type. More...
kStatus | kSerializer_SetEndianness (kSerializer serializer, kEndianness endianness)
| Explicitly sets the endianness (byte ordering) of encoded/decoded values. More...
kStatus | kSerializer_SetSizeEncoding (kSerializer serializer, k32u byteCount)
| Explicitly sets the number of bytes used to encode/decode kSize and kSSize values. More...
kStatus | kSerializer_SetVersion (kSerializer serializer, kAssembly assembly, kVersion version)
| Sets the version to use when serializing types. More...
k32u | kSerializer_SizeEncoding (kSerializer serializer)
| Reports the number of bytes used to encode/decode kSize and kSSize values. More...
kStream | kSerializer_Stream (kSerializer serializer)
| Gets the underlying stream. More...
kStatus | kSerializer_Write16s (kSerializer serializer, k16s data)
| Writes a k16s value. More...
kStatus | kSerializer_Write16sArray (kSerializer serializer, const k16s *data, kSize count)
| Writes a k16s array. More...
kStatus | kSerializer_Write16u (kSerializer serializer, k16u data)
| Writes a k16u value. More...
kStatus | kSerializer_Write16uArray (kSerializer serializer, const k16u *data, kSize count)
| Writes a k16u array. More...
kStatus | kSerializer_Write32f (kSerializer serializer, k32f data)
| Writes a k32f value. More...
kStatus | kSerializer_Write32fArray (kSerializer serializer, const k32f *data, kSize count)
| Writes a k32f array. More...
kStatus | kSerializer_Write32s (kSerializer serializer, k32s data)
| Writes a k32s value. More...
kStatus | kSerializer_Write32sArray (kSerializer serializer, const k32s *data, kSize count)
| Writes a k32s array. More...
kStatus | kSerializer_Write32u (kSerializer serializer, k32u data)
| Writes a k32u value. More...
kStatus | kSerializer_Write32uArray (kSerializer serializer, const k32u *data, kSize count)
| Writes a k32u array. More...
kStatus | kSerializer_Write64f (kSerializer serializer, k64f data)
| Writes a k64f value. More...
kStatus | kSerializer_Write64fArray (kSerializer serializer, const k64f *data, kSize count)
| Writes a k64f array. More...
kStatus | kSerializer_Write64s (kSerializer serializer, k64s data)
| Writes a k64s value. More...
kStatus | kSerializer_Write64sArray (kSerializer serializer, const k64s *data, kSize count)
| Writes a k64s array. More...
kStatus | kSerializer_Write64u (kSerializer serializer, k64u data)
| Writes a k64u value. More...
kStatus | kSerializer_Write64uArray (kSerializer serializer, const k64u *data, kSize count)
| Writes a k64u array. More...
kStatus | kSerializer_Write8s (kSerializer serializer, k8s data)
| Writes a k8s value. More...
kStatus | kSerializer_Write8sArray (kSerializer serializer, const k8s *data, kSize count)
| Writes a k8s array. More...
kStatus | kSerializer_Write8u (kSerializer serializer, k8u data)
| Writes a k8u value. More...
kStatus | kSerializer_Write8uArray (kSerializer serializer, const k8u *data, kSize count)
| Writes a k8u array. More...
kStatus | kSerializer_WriteByte (kSerializer serializer, kByte data)
| Writes a kByte value. More...
kStatus | kSerializer_WriteByteArray (kSerializer serializer, const void *data, kSize count)
| Writes a kByte array. More...
kStatus | kSerializer_WriteChar (kSerializer serializer, kChar data)
| Writes a kChar value. More...
kStatus | kSerializer_WriteCharArray (kSerializer serializer, const kChar *data, kSize count)
| Writes a kChar array. More...
kStatus | kSerializer_WriteItems (kSerializer serializer, kType type, kTypeVersion version, const void *items, kSize count)
| Writes an array of values or objects. More...
kStatus | kSerializer_WriteObject (kSerializer serializer, kObject object)
| Writes an object to the underlying stream. More...
kStatus | kSerializer_WriteSize (kSerializer serializer, kSize data)
| Writes a kSize value. More...
kStatus | kSerializer_WriteSizeArray (kSerializer serializer, const kSize *data, kSize count)
| Writes a kSize array. More...
kStatus | kSerializer_WriteSSize (kSerializer serializer, kSSize data)
| Writes a kSSize value. More...
kStatus | kSerializer_WriteSSizeArray (kSerializer serializer, const kSSize *data, kSize count)
| Writes a kSSize array. More...
kStatus | kSerializer_WriteText (kSerializer serializer, const kChar *data)
| Writes a null-terminated kChar array. More...
kStatus | kSerializer_WriteType (kSerializer serializer, kType type, kTypeVersion *version)
| Writes a type code. More...
Public Member Functions inherited from kObject
kAlloc | kObject_Alloc (kObject object)
| Gets the memory allocator associated with this object. More...
kStatus | kObject_Clone (kObject *object, kObject source, kAlloc allocator)
| Constructs a new object by copying an existing object, including any aggregated child elements. More...
kStatus | kObject_Destroy (kObject object)
| Destroys the object. More...
kStatus | kObject_Dispose (kObject object)
| Destroys the object and any aggregated child elements. More...
kBool | kObject_Equals (kObject object, kObject other)
| Determines whether the object is equal to another object. More...
kSize | kObject_HashCode (kObject object)
| Gets a hash code representing the state of this object. More...
kBool | kObject_Is (kObject object, kType type)
| Determines whether this object is an instance of the specified type. More...
kBool | kObject_IsShared (kObject object)
| Reports whether the object is currently shared (reference count greater than one). More...
kStatus | kObject_SetPool (kObject object, kObjectPool pool)
| Sets the object pool associated with this object. More...
kStatus | kObject_Share (kObject object)
| Increments the reference count associated with this object. More...
kSize | kObject_Size (kObject object)
| Estimates the memory consumed by this object, including any aggregated child elements. More...
kType | kObject_Type (kObject object)
| Returns the type of the object. More...

## Related
#define | kSerializer_ReadItemsT(kSerializer_serializer, kType_type, kTypeVersion_version, TPtr_items, kSize_count)
| Reads an array of values or objects. More...
#define | kSerializer_WriteItemsT(kSerializer_serializer, kType_type, kTypeVersion_version, TPtr_items, kSize_count)
| Writes an array of values or objects. More...

## Additional Inherited Members
Protected Member Functions inherited from kObject
kStatus | kObject_FreeMem (kObject object, void *mem)
| Protected method called by derived classes to free memory using the object's allocator. More...
kStatus | kObject_FreeMemRef (kObject object, void *mem)
| Protected method called by derived classes to free memory (and reset the provided memory pointer to kNULL) using the object's allocator. More...
kStatus | kObject_GetMem (kObject object, kSize size, void *mem)
| Protected method called by derived classes to allocate memory using the object's allocator. More...
kStatus | kObject_GetMemZero (kObject object, kSize size, void *mem)
| Protected method called by derived classes to allocate and zero memory using the object's allocator. More...
kStatus | kObject_Init (kObject object, kType type, kAlloc alloc)
| Protected method called by derived classes to initialize the kObject base class. More...
kStatus | kObject_VDisposeItems (kObject object)
| Protected virtual method that destroys any aggregated child objects associated with a collection. More...
kBool | kObject_VEquals (kObject object, kObject other)
| Protected virtual method that compares two objects for equality. More...
kSize | kObject_VHashCode (kObject object)
| Protected virtual method that calculates a hash code representing the object instance. More...
kStatus | kObject_VInitClone (kObject object, kObject source, kAlloc allocator)
| Protected virtual method that clones (makes a deep copy of) the specified source object. More...
kStatus | kObject_VRelease (kObject object)
| Protected virtual method that deallocates any resources owned by the object. More...
kSize | kObject_VSize (kObject object)
| Protected virtual method that calculates the total size (in bytes) of the object instance. More...

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

- Io/kSerializer.h