GwySerializable

GwySerializable — Abstract interface for serializable objects.

Synopsis




struct      GwySerializableIface;
struct      GwySerializable;
GByteArray* (*GwySerializeFunc)             (GObject *serializable,
                                             GByteArray *buffer);
GObject*    (*GwyDeserializeFunc)           (const guchar *buffer,
                                             gsize size,
                                             gsize *position);
struct      GwySerializeSpec;
struct      GwySerializeItem;
GByteArray* gwy_serializable_serialize      (GObject *serializable,
                                             GByteArray *buffer);
GObject*    gwy_serializable_deserialize    (const guchar *buffer,
                                             gsize size,
                                             gsize *position);
GObject*    gwy_serializable_duplicate      (GObject *object);
void        gwy_serializable_clone          (GObject *source,
                                             GObject *copy);
GByteArray* gwy_serialize_pack_object_struct
                                            (GByteArray *buffer,
                                             const guchar *object_name,
                                             gsize nspec,
                                             const GwySerializeSpec *spec);
gboolean    gwy_serialize_unpack_object_struct
                                            (const guchar *buffer,
                                             gsize size,
                                             gsize *position,
                                             const guchar *object_name,
                                             gsize nspec,
                                             GwySerializeSpec *spec);
GByteArray* gwy_serialize_object_items      (GByteArray *buffer,
                                             const guchar *object_name,
                                             gsize nitems,
                                             const GwySerializeItem *items);
GwySerializeItem* gwy_deserialize_object_hash
                                            (const guchar *buffer,
                                             gsize size,
                                             gsize *position,
                                             const guchar *object_name,
                                             gsize *nitems);

Object Hierarchy


  GInterface
   +----GwySerializable

Prerequisites

GwySerializable requires GObject.

Known Implementations

GwySerializable is implemented by GwySIUnit and GwyContainer.

Description

GwySerializable is an abstract interface for value-like object that can be serialized and deserialized. You can serialize any object implementing this interface with gwy_serializable_serialize() and the restore (deserialize) it with gwy_serializable_deserialize(). It is also posible it duplicate any such object with gwy_serializable_duplicate().

The only functions that should be used for implementation of serialization and deserialization in your classes, are the most high-level ones: gwy_serialize_pack_object_struct(), gwy_serialize_unpack_object_struct(), gwy_serialize_object_items(), and gwy_deserialize_object_hash(). The former two are useful for struct-like objects (most objects are of this kind), the latter two for hash-like objects, i.e., objects that can contain components of arbitrary name and type.

All the low-level functions are deprecated and will be removed in Gwyddion 2.0.

Details

struct GwySerializableIface

struct GwySerializableIface {

    GwySerializeFunc serialize;
    GwyDeserializeFunc deserialize;
    void (*clone)(GObject *source, GObject *copy);
    GObject* (*duplicate)(GObject *object);
};

The methods a serializable objects has to implement.

GwySerializeFunc serialize Serialization method (obligatory), see GwySerializeFunc for description.
GwyDeserializeFunc deserialize Restore method (obligatory), see GwyDeserializeFunc for description.
void (*clone) (GObject *source, GObject *copy) Clone method (obligatory). Copies complete object `value' to an existing object of the same type. This method is called from copy's class if source and copy classes differ.
GObject* (*duplicate) (GObject *object) Duplication method (optional). Creates a duplicate of an object.

struct GwySerializable

struct GwySerializable;


GwySerializeFunc ()

GByteArray* (*GwySerializeFunc)             (GObject *serializable,
                                             GByteArray *buffer);

The type of serialization method, see gwy_serializable_serialize() for description.

serializable : An object to serialize.
buffer : A buffer to append the representation to, may be NULL indicating a new one should be allocated.
Returns : buffer with serialized object appended.

GwyDeserializeFunc ()

GObject*    (*GwyDeserializeFunc)           (const guchar *buffer,
                                             gsize size,
                                             gsize *position);

The type of deserialization method, see gwy_serializable_deserialize() for description.

buffer : A buffer containing a serialized object.
size : The size of buffer.
position : The current position in buffer.
Returns : A newly created (restored) object.

struct GwySerializeSpec

struct GwySerializeSpec {

    guchar ctype;
    const guchar *name;
    gpointer value;
    guint32 *array_size;
};

A structure containing information for one object/struct component serialization or deserialization.

This component information is used in gwy_serialize_pack_object_struct() and gwy_serialize_unpack_object_struct() suitable for (de)serialization of struct-like objects.

guchar ctype Component type, as in gwy_serialize_pack_object_struct().
const guchar *name Component name as a null terminated string.
gpointer value Pointer to component (always add one level of indirection; for an object, a GObject** pointer should be stored).
guint32 *array_size Pointer to array size if component is an array, NULL otherwise.

struct GwySerializeItem

struct GwySerializeItem {

    guchar ctype;
    const guchar *name;
    GwySerializeValue value;
    guint32 array_size;
};

A structure containing information for one object/struct component serialization or deserialization.

This component information is used in gwy_serialize_object_items() and gwy_deserialize_object_hash() suitable for (de)serialization of hash-like objects.

guchar ctype Component type, as in gwy_serialize_object_items().
const guchar *name Component name as a null terminated string.
GwySerializeValue value Component value.
guint32 array_size Array size if component is an array, unused otherwise.

gwy_serializable_serialize ()

GByteArray* gwy_serializable_serialize      (GObject *serializable,
                                             GByteArray *buffer);

Serializes an object to byte buffer.

serializable : A GObject implementing GwySerializable interface.
buffer : A buffer to which the serialized object should be appended, or NULL.
Returns : buffer or a newly allocated GByteArray with serialized object appended.

gwy_serializable_deserialize ()

GObject*    gwy_serializable_deserialize    (const guchar *buffer,
                                             gsize size,
                                             gsize *position);

Restores a serialized object from byte buffer.

The newly created object has reference count according to its nature, thus a GtkObject will have a floating reference, a GObject will have a refcount of 1, etc.

buffer : A block of memory of size size contaning object representation.
size : The size of buffer.
position : The position of the object in buffer, it's updated to point after it.
Returns : A newly created object.

gwy_serializable_duplicate ()

GObject*    gwy_serializable_duplicate      (GObject *object);

Creates a copy of an object.

If the object doesn't support duplication natively, it's brute-force serialized and then deserialized, this may be quite inefficient, namely for large objects.

You can duplicate a NULL, too, but you are discouraged from doing it.

object : An object implementing GwySerializable interface.
Returns : The newly created object copy. However if the object is a singleton, object itself (with incremented reference count) can be returned, too.

gwy_serializable_clone ()

void        gwy_serializable_clone          (GObject *source,
                                             GObject *copy);

Makes an object identical to another object of the same type.

More precisely, source may be subclass of copy (the extra information is lost then).

source : An object implementing GwySerializable interface.
copy : An object of the same type as source to modify after it.

gwy_serialize_pack_object_struct ()

GByteArray* gwy_serialize_pack_object_struct
                                            (GByteArray *buffer,
                                             const guchar *object_name,
                                             gsize nspec,
                                             const GwySerializeSpec *spec);

Appends serialization of object with g_type_name() object_name and components described by spec to buffer in gwy-file format.

Here's how a serialization method of a simple object whose state is described by a single real number foo could look (without error checking):

static guchar*
my_object_serialize(GObject *obj,
                    guchar *buffer,
                    gsize *size)
{
    MyObject *my_object = MY_OBJECT(obj);
    GwySerializeSpec spec[] = {
        { 'd', "foo", &my_object->foo, NULL, },
    };

    return gwy_serialize_pack_object_struct(buffer, size,
                                            "MyObject",
                                            G_N_ELEMENTS(spec), spec);
}
buffer :A buffer to which the serialized components should be appended.
object_name :The g_type_name() of the object.
nspec :The number of items in spec.
spec :The components to serialize.
Returns :The buffer with serialization of spec components appended.

gwy_serialize_unpack_object_struct ()

gboolean    gwy_serialize_unpack_object_struct
                                            (const guchar *buffer,
                                             gsize size,
                                             gsize *position,
                                             const guchar *object_name,
                                             gsize nspec,
                                             GwySerializeSpec *spec);

Deserializes an object with named components packed into gwy-file format by gwy_serialize_pack_object_struct().

Extra components are ignored (but cause a warning), components of different type than expected cause failure, missing components are not detected.

It is safe to pass pointers to existing non-atomic objects (strings, arrays, objects) in spec values, they will be dereferenced and freed as necessary when an unpacked value is about to replace them. For the same reason it is an error to pass pointers to unintialized memory there, always initialize non-atomic spec values to NULL pointers, at least.

Caller is responsible for use/clean-up of these values if deserialization succeeds or not.

Here's how a deserialization method of a simple object whose state is described by a single real number foo could look (without error checking):

static GObject*
my_object_deserialize(const guchar *buffer,
                      gsize size,
                      gsize *position)
{
    double foo = 1.0;
    GwySerializeSpec spec[] = {
        { 'd', "foo", &foo, NULL, },
    };
    MyObject *my_object;

    gwy_serialize_unpack_object_struct(buffer, size, position,
                                       "MyObject",
                                       G_N_ELEMENTS(spec), spec);
    return my_object_new(foo);
}
buffer :A memory location containing a serialized object at position position.
size :Current size of buffer, new size is returned here.
position :The position of the object in buffer, it's updated to point after it.
object_name :The g_type_name() of the object.
nspec :The number of items in spec.
spec :The components to deserialize.
Returns :Whether the unpacking succeeded (see description body for definition of success and failure).

gwy_serialize_object_items ()

GByteArray* gwy_serialize_object_items      (GByteArray *buffer,
                                             const guchar *object_name,
                                             gsize nitems,
                                             const GwySerializeItem *items);

Serializes an object to buffer in gwy-file format.

More precisely, it appends serialization of object with g_type_name() object_name with components described by items to buffer.

buffer : A buffer to which the serialized components should be appended, or NULL.
object_name : The g_type_name() of the object.
nitems : The number of items items.
items : The components to serialize.
Returns : buffer or a newly allocated GByteArray with serialization of items components appended.

gwy_deserialize_object_hash ()

GwySerializeItem* gwy_deserialize_object_hash
                                            (const guchar *buffer,
                                             gsize size,
                                             gsize *position,
                                             const guchar *object_name,
                                             gsize *nitems);

Deserializes an object with arbitrary components from gwy-file format.

This function works like gwy_serialize_unpack_object_struct(), except that it does not use any a priori knowledge of what the object contains. So instead of filling values in supplied GwySerializeSpec's, it constructs GwySerializeItem's completely from what is found in buffer. It does considerably less sanity checks and even allows several components of the same name.

buffer : A block of memory of size size contaning object representation.
size : The size of buffer.
position : Current position in buffer, will be updated to point after object.
object_name : The g_type_name() of the object.
nitems : Where the number of deserialized components should be stored.
Returns : A newly allocated array of deserialized components. Note the name fields of GwySerializeSpec's point to buffer and thus are valid only as long as buffer is; any arrays or strings are newly allocated and must be reused or freed by caller.