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);
GObject*    (*GwyDuplicateFunc)             (GObject *object);
struct      GwySerializeSpec;
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_serialize_store_int32       (GByteArray *buffer,
                                             gsize position,
                                             guint32 value);
GByteArray* gwy_serialize_pack              (GByteArray *buffer,
                                             const gchar *templ,
                                             ...);
gboolean    gwy_serialize_unpack_boolean    (const guchar *buffer,
                                             gsize size,
                                             gsize *position);
guchar      gwy_serialize_unpack_char       (const guchar *buffer,
                                             gsize size,
                                             gsize *position);
guchar*     gwy_serialize_unpack_char_array (const guchar *buffer,
                                             gsize size,
                                             gsize *position,
                                             gsize *asize);
gint32      gwy_serialize_unpack_int32      (const guchar *buffer,
                                             gsize size,
                                             gsize *position);
gint32*     gwy_serialize_unpack_int32_array
                                            (const guchar *buffer,
                                             gsize size,
                                             gsize *position,
                                             gsize *asize);
gint64      gwy_serialize_unpack_int64      (const guchar *buffer,
                                             gsize size,
                                             gsize *position);
gint64*     gwy_serialize_unpack_int64_array
                                            (const guchar *buffer,
                                             gsize size,
                                             gsize *position,
                                             gsize *asize);
gdouble     gwy_serialize_unpack_double     (const guchar *buffer,
                                             gsize size,
                                             gsize *position);
gdouble*    gwy_serialize_unpack_double_array
                                            (const guchar *buffer,
                                             gsize size,
                                             gsize *position,
                                             gsize *asize);
guchar*     gwy_serialize_unpack_string     (const guchar *buffer,
                                             gsize size,
                                             gsize *position);
gsize       gwy_serialize_check_string      (const guchar *buffer,
                                             gsize size,
                                             gsize position,
                                             const guchar *compare_to);
GByteArray* gwy_serialize_pack_struct       (GByteArray *buffer,
                                             gsize nspec,
                                             const GwySerializeSpec *spec);
gboolean    gwy_serialize_unpack_struct     (const guchar *buffer,
                                             gsize size,
                                             gsize nspec,
                                             const GwySerializeSpec *spec);
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,
                                             const GwySerializeSpec *spec);

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().

There are quite a few helper functions available for implementation of serialization and deserialization in you classes, most high-level (and thus probably most useful) are gwy_serialize_pack_object_struct() and gwy_serialize_unpack_object_struct().

Details

struct GwySerializableIface

struct GwySerializableIface {

    GTypeInterface parent_class;

    GwySerializeFunc serialize;
    GwyDeserializeFunc deserialize;
    GwyDuplicateFunc duplicate;
};


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.

GwyDuplicateFunc ()

GObject*    (*GwyDuplicateFunc)             (GObject *object);

The type of duplication method, see gwy_serializable_duplicate() for description.

object : An object to duplicate.
Returns : A copy of 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.

guchar ctype Component type, as in gwy_serialize_pack().
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.

gwy_serializable_serialize ()

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

Serializes an object implementing GwySerializable interface.

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 GBaseInitFunc with serialized object appended.

gwy_serializable_deserialize ()

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

Restores a serialized object.

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 object 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 : A GObject 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_serialize_store_int32 ()

void        gwy_serialize_store_int32       (GByteArray *buffer,
                                             gsize position,
                                             guint32 value);

Stores a 32bit integer to a buffer.

buffer : A buffer to which the value should be stored.
position : Position in the buffer to store value to.
value : A 32bit integer.

gwy_serialize_pack ()

GByteArray* gwy_serialize_pack              (GByteArray *buffer,
                                             const gchar *templ,
                                             ...);

Serializes a list of plain atomic types.

The templ string can contain following characters:

'b' for a a boolean, 'c' for a character, 'i' for a 32bit integer, 'q' for a 64bit integer, 'd' for a double, 's' for a null-terminated string.

'C' for a character array (a gsize length followed by a pointer to the array), 'I' for a 32bit integer array, 'Q' for a 64bit integer array, 'D' for a double array.

'o' for a serializable object.

FIXME: this function currently doesn't create architecture-independent representations, it just copies the memory.

buffer : A buffer to which the serialized values should be appended, or NULL.
templ : A template string.
... : A list of atomic values to serialize.
Returns : buffer or a newly allocated GByteArray with serialization of given values appended.

gwy_serialize_unpack_boolean ()

gboolean    gwy_serialize_unpack_boolean    (const guchar *buffer,
                                             gsize size,
                                             gsize *position);

Deserializes a one boolean.

buffer : A memory location containing a serialized boolean at position position.
size : The size of buffer.
position : The position of the character in buffer, it's updated to point after it.
Returns : The boolean as gboolean.

gwy_serialize_unpack_char ()

guchar      gwy_serialize_unpack_char       (const guchar *buffer,
                                             gsize size,
                                             gsize *position);

Deserializes a one character.

buffer : A memory location containing a serialized character at position position.
size : The size of buffer.
position : The position of the character in buffer, it's updated to point after it.
Returns : The character as guchar.

gwy_serialize_unpack_char_array ()

guchar*     gwy_serialize_unpack_char_array (const guchar *buffer,
                                             gsize size,
                                             gsize *position,
                                             gsize *asize);

Deserializes a character array.

buffer : A memory location containing a serialized character array at position position.
size : The size of buffer.
position : The position of the array in buffer, it's updated to point after it.
asize : Where the size of the array is to be returned.
Returns : The unpacked character array (newly allocated).

gwy_serialize_unpack_int32 ()

gint32      gwy_serialize_unpack_int32      (const guchar *buffer,
                                             gsize size,
                                             gsize *position);

Deserializes a one 32bit integer.

buffer : A memory location containing a serialized 32bit integer at position position.
size : The size of buffer.
position : The position of the integer in buffer, it's updated to point after it.
Returns : The integer as gint32.

gwy_serialize_unpack_int32_array ()

gint32*     gwy_serialize_unpack_int32_array
                                            (const guchar *buffer,
                                             gsize size,
                                             gsize *position,
                                             gsize *asize);

Deserializes an int32 array.

buffer : A memory location containing a serialized int32 array at position position.
size : The size of buffer.
position : The position of the array in buffer, it's updated to point after it.
asize : Where the size of the array is to be returned.
Returns : The unpacked 32bit integer array (newly allocated).

gwy_serialize_unpack_int64 ()

gint64      gwy_serialize_unpack_int64      (const guchar *buffer,
                                             gsize size,
                                             gsize *position);

Deserializes a one 64bit integer.

buffer : A memory location containing a serialized 64bit integer at position position.
size : The size of buffer.
position : The position of the integer in buffer, it's updated to point after it.
Returns : The integer as gint64.

gwy_serialize_unpack_int64_array ()

gint64*     gwy_serialize_unpack_int64_array
                                            (const guchar *buffer,
                                             gsize size,
                                             gsize *position,
                                             gsize *asize);

Deserializes an int64 array.

buffer : A memory location containing a serialized int64 array at position position.
size : The size of buffer.
position : The position of the array in buffer, it's updated to point after it.
asize : Where the size of the array is to be returned.
Returns : The unpacked 64bit integer array (newly allocated).

gwy_serialize_unpack_double ()

gdouble     gwy_serialize_unpack_double     (const guchar *buffer,
                                             gsize size,
                                             gsize *position);

Deserializes a one double.

buffer : A memory location containing a serialized double at position position.
size : The size of buffer.
position : The position of the integer in buffer, it's updated to point after it.
Returns : The integer as gdouble.

gwy_serialize_unpack_double_array ()

gdouble*    gwy_serialize_unpack_double_array
                                            (const guchar *buffer,
                                             gsize size,
                                             gsize *position,
                                             gsize *asize);

Deserializes an double array.

buffer : A memory location containing a serialized double array at position position.
size : The size of buffer.
position : The position of the array in buffer, it's updated to point after it.
asize : Where the size of the array is to be returned.
Returns : The unpacked double array (newly allocated).

gwy_serialize_unpack_string ()

guchar*     gwy_serialize_unpack_string     (const guchar *buffer,
                                             gsize size,
                                             gsize *position);

Deserializes a one nul-terminated string.

buffer : A memory location containing a serialized nul-terminated string at position position.
size : The size of buffer.
position : The position of the string in buffer, it's updated to point after it.
Returns : A newly allocated, nul-terminated string.

gwy_serialize_check_string ()

gsize       gwy_serialize_check_string      (const guchar *buffer,
                                             gsize size,
                                             gsize position,
                                             const guchar *compare_to);

Check whether size bytes of memory in buffer can be interpreted as a nul-terminated string, and eventually whether it's equal to compare_to.

When compare_to is NULL, the comparsion is not performed.

buffer : A memory location containing a nul-terminated string at position position.
size : The size of buffer.
position : The position of the string in buffer.
compare_to : String to compare buffer to, or NULL.
Returns : The length of the nul-terminated string including the nul character; zero otherwise.

gwy_serialize_pack_struct ()

GByteArray* gwy_serialize_pack_struct       (GByteArray *buffer,
                                             gsize nspec,
                                             const GwySerializeSpec *spec);

Serializes a struct with named and somewhat typed fields.

For object serialization gwy_serialize_pack_object_struct() should be more convenient and less error prone.

buffer : A buffer to which the serialized components should be appended, or NULL.
nspec : The number of items in spec.
spec : The components to serialize.
Returns : buffer or a newly allocated GByteArray with serialization of spec components appended.

gwy_serialize_unpack_struct ()

gboolean    gwy_serialize_unpack_struct     (const guchar *buffer,
                                             gsize size,
                                             gsize nspec,
                                             const GwySerializeSpec *spec);

Deserializes a structure with named components packed by gwy_serialize_pack_struct().

Extra components are ignored, components of different type than expected cause failure, missing components are not detected.

For object deserialization gwy_serialize_unpack_object_struct() should be more convenient and less error prone.

buffer : A memory location containing a serialized structure.
size : The size of buffer.
nspec : The number of items in spec.
spec : The components to deserialize.
Returns : TRUE if the unpacking succeeded, FALSE otherwise (some fields may be unpacked in this case).

gwy_serialize_pack_object_struct ()

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

Packs a struct as an object.

This is a wrapper around gwy_serialize_pack_struct(), taking care of adding type name and packed object size.

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,
                                             const GwySerializeSpec *spec);

Deserializes an object with named components packed by gwy_serialize_pack_object_struct().

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 gwy_serialize_unpack_struct() for definition of success).