Top | ![]() |
![]() |
![]() |
![]() |
GQuark | gwy_deserialize_error_quark () |
gboolean | gwy_serialize_gio () |
GObject * | gwy_deserialize_memory () |
Methods of GwySerializable abstract from the precise byte-for-byte representation of serialised objects. It is conceivable to imagine using for instance HDF5 or XML as the binary format. Functions available here at this moment, however, implement the GWY binary data format, version 3.
Note the initial reference counts of restored objects are according to their nature. For instance, a GInitiallyUnowned will have a floating reference, a plain GObject will have a reference count of 1, etc.
The following information is not necessary for implementing GwySerializable interface in your classes, but it can help prevent wrong decision about serialised representation of your objects. Also, it might help implementing a different serialisation backend than GWY files.
Serialization occurs in several steps.
First, all objects are recursively asked to calulcate the number of named data items they will serialise to
(or provide a reasonable upper estimate of this number). This is done simply by calling gwy_serializable_n_items()
on the top-level object, objects that contain other objects must call gwy_serializable_n_items()
on these contained
objects and sum the results.
Second, a GwySerializableItems item list is created, with size calculated in the first step. All objects
are then recursively asked to add items representing their data to this list. This is done simply by calling
gwy_serializable_itemize()
on the top-level object. The objects may sometimes need to represent certain data
differently than the internal representation is, however, expensive transforms should be avoided, especially for
arrays. This step can allocate temporary structures.
Third, sizes of each object are calcuated and stored into the object-header items created by
gwy_serializable_itemize()
. This again is done recursively, but the objects do not participate, the calculation
works with the itemised list. This step might not be necessary for other storage formats.
Subsequently, the object tree flattened into an item list is written to the output stream, byte-swapping or otherwise normalizing the data on the fly if necessary. This part strongly depends on the storage format.
Finally, virtual method done()
is called for all objects. This step frees the temporary storage allocated in
the itemization step, if any. This is not done recursively so that objects need not to implement this method, even
if they contain other objects, if they themselves do not create any temporary data during itemize()
. The methods
are called in the inverse order than the objects appear in the list, i.e. the most inner and last objects are
processed first. This means that if done()
of an object is invoked, all its contained objects have been already
processed. At the very end the item list is freed too.
GQuark
gwy_deserialize_error_quark (void
);
Gets the error domain for deserialisation.
See and use GWY_DESERIALIZE_ERROR
.
gboolean gwy_serialize_gio (GwySerializable *serializable
,GOutputStream *output
,GError **error
);
Serialises an object to GIO stream in GWY format.
The data writing employs internal buffering. If the output stream is already buffered (e.g., GBufferedOutputStream), the output will be unnecessarily buffered twice.
GObject * gwy_deserialize_memory (const guchar *buffer
,gsize size
,gsize *bytes_consumed
,GwyErrorList **error_list
);
Deserialises an object in GWY format from plain memory buffer.
buffer |
Memory containing the serialised representation of one object. |
|
size |
Size of |
|
bytes_consumed |
Location to store the number of bytes actually consumed
from |
|
error_list |
Location to store the errors occuring, |
#define GWY_DESERIALIZE_ERROR gwy_deserialize_error_quark()
Error domain for deserialisation.
Errors in this domain will be from the GwyDeserializeError enumeration. See GError for information on error domains.
Error codes returned by deserialisation.
In the error code descriptions, fatal error means aborting of deserialisation of the object that is just being unpacked. Non-fatal errors are competely recoverable. If the deserialisation of a contained object is aborted, the unpacking of the container object still continues. Therefore, fatal errors are truly fatal only if they occur for the top-level object.
There is too much data to represent given object. This error is non-fatal: the extra data is just ignored. |
||
Unexpected item was encountered. This error is non-fatal: such item is just ignored. |
||
Invalid information (for instance an out-of-bounds value) was encountered and replaced (for instance by a default value). This error is non-fatal. Implementations should use it when they encounter invalid information but are able to proceed. |
||
Distinguishes fatal and non-fatal errors (fatal give non-zero value when masked with this mask). |
||
Data ends in the middle of some item or there is not enough data to represent given object. This error is fatal. |
||
Size is not representable on this system. This can occur on legacy 32bit systems, however, they are incapable of holding such large data in core anyway. This error is fatal. |
||
Representation of an object of unknown or deserialisation-incapable type was found. This error is fatal. |
||
Uknown data type (GwySerializableCType) was encountered. This error is fatal. |
||
Serialised string is not valid UTF-8. This error is fatal. |
||
Object representation is logicaly inconsistent or otherwise invalid. Reserved for classes to indicate data errors on levels higher than physical representation. This error is fatal. |