Zen API
 All Classes Files Functions Variables Typedefs Friends Macros Modules Pages
kSerializer Class Reference

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;
{
//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
}
{
kObject_Destroy(writer);
}
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)
{
}
//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.

#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;
{
//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));
}
{
kObject_Destroy(reader);
}
return kOK;
}
Inheritance diagram for kSerializer:
Inheritance graph

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...
 
kBool kObject_HasForeignData (kObject object)
 Reports whether the object, including aggregated child elements, contains any foreign memory references. 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...
 
kBool kObject_VHasForeignData (kObject object)
 Protected virtual method that reports whether the object, including aggregated child elements, contains any foreign memory references. 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: