110 lines
4.7 KiB
C
110 lines
4.7 KiB
C
/**
|
|
* @file kDat5Serializer.h
|
|
* @brief Declares the kDat5Serializer class.
|
|
*
|
|
* @internal
|
|
* Copyright (C) 2008-2021 by LMI Technologies Inc.
|
|
* Licensed under the MIT License.
|
|
* Redistributed files must retain the above copyright notice.
|
|
*/
|
|
#ifndef K_API_DAT5_SERIALIZER_H
|
|
#define K_API_DAT5_SERIALIZER_H
|
|
|
|
#include <kApi/kApiDef.h>
|
|
#include <kApi/Io/kDat5Serializer.x.h>
|
|
|
|
/**
|
|
* @class kDat5Serializer
|
|
* @extends kSerializer
|
|
* @ingroup kApi-Io
|
|
* @brief Serializes/deserializes objects using kDat5 format.
|
|
*/
|
|
//typedef kSerializer kDat5Serializer; --forward-declared in kApiDef.x.h
|
|
|
|
/**
|
|
* Constructs a kDat5Serializer object.
|
|
*
|
|
* @public @memberof kDat5Serializer
|
|
* @param serializer Receives the constructed object.
|
|
* @param stream Stream for reading or writing.
|
|
* @param allocator Memory allocator (or kNULL for default).
|
|
* @return Operation status.
|
|
*/
|
|
kFx(kStatus) kDat5Serializer_Construct(kDat5Serializer* serializer, kStream stream, kAlloc allocator);
|
|
|
|
/**
|
|
* Writes a labelled object to the underlying stream.
|
|
*
|
|
* @public @memberof kDat5Serializer
|
|
* @param serializer Serializer object.
|
|
* @param object Object to be serialized.
|
|
* @param label Object label.
|
|
* @return Operation status.
|
|
*/
|
|
kFx(kStatus) kDat5Serializer_WriteData(kDat5Serializer serializer, kObject object, const kChar* label);
|
|
|
|
/**
|
|
* Reads a labelled object from the underlying stream.
|
|
*
|
|
* @public @memberof kDat5Serializer
|
|
* @param serializer Serializer object.
|
|
* @param object Receives deserialized object.
|
|
* @param label Receives object label.
|
|
* @param capacity Label capacity.
|
|
* @param allocator Memory allocator (or kNULL for default).
|
|
* @return Operation status.
|
|
*/
|
|
kFx(kStatus) kDat5Serializer_ReadData(kDat5Serializer serializer, kObject* object, kChar* label, kSize capacity, kAlloc allocator);
|
|
|
|
/**
|
|
* Enables the use of compression in serialization.
|
|
*
|
|
* By default, kDat5Serializer data is uncompressed. This method can be used to specify a compression
|
|
* algorithm to be used when serializing objects.
|
|
*
|
|
* When compression is enabled via this method, metadata is encoded in the stream such that the
|
|
* required decompression approach will be automatically detected during object deserialization.
|
|
* Accordingly, this method should <em>not</em> be called when deserializing data.
|
|
*
|
|
* The use of compression requires that the underlying stream object (e.g., kFile) created by the
|
|
* <em>receiver</em> provides a read buffer. Configure the read stream to allocate a read buffer
|
|
* before passing the stream to the deserializer constructor.
|
|
*
|
|
* The Zen library does not itself provide compression algorithms. If compression support is required,
|
|
* an additional assembly that implements compression must first be loaded. Refer to the documentation
|
|
* for the selected compression stream type for information about additional requirements or restrictions
|
|
* that might apply.
|
|
*
|
|
* Support for this feature was introduced in Zen 6.2.1. Older versions cannot read or write compressed content.
|
|
*
|
|
* @public @memberof kDat5Serializer
|
|
* @param serializer Serializer object.
|
|
* @param algorithm Compression algorithm type (null to disable).
|
|
* @param level Compression level; accepts kCompressionPreset value or compressor-specific value.
|
|
* @return Operation status.
|
|
*/
|
|
kFx(kStatus) kDat5Serializer_EnableCompression(kDat5Serializer serializer, kCompressionType algorithm, k32s level);
|
|
|
|
/**
|
|
* Saves an object to file using the specified compression type.
|
|
*
|
|
* The file produced by this function can be loaded with kSerializer_LoadObject or kLoad5.
|
|
*
|
|
* The Zen library does not itself provide compression algorithms. If compression support is required,
|
|
* an additional assembly that implements compression must first be loaded. Refer to the documentation
|
|
* for the selected compression stream type for information about additional requirements or restrictions
|
|
* that might apply.
|
|
*
|
|
* Support for this feature was introduced in Zen 6.2.1. Older versions cannot read or write compressed content.
|
|
*
|
|
* @public @memberof kDat5Serializer
|
|
* @param object Object to be serialized.
|
|
* @param filePath Path of the file to save.
|
|
* @param algorithm Compression algorithm type.
|
|
* @param level Compression level; accepts kCompressionPreset value or compressor-specific value.
|
|
* @return Operation status.
|
|
*/
|
|
kFx(kStatus) kDat5Serializer_SaveCompressed(kObject object, const kChar* filePath, kCompressionType algorithm, k32s level);
|
|
|
|
#endif
|