![]() |
![]() |
Gwyddion Library Reference Manual | ![]() |
|
---|---|---|---|---|
Top | Description | Object Hierarchy | Prerequisites | Known Implementations |
#include <libgwyddion/gwyddion.h> GwySerializable; GByteArray * (*GwySerializeFunc) (GObject *serializable
,GByteArray *buffer
); GObject * (*GwyDeserializeFunc) (const guchar *buffer
,gsize size
,gsize *position
); struct GwySerializableIface; GwySerializeSpec; GwySerializeValue; 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
); gsize gwy_serializable_get_size (GObject *serializable
); gsize gwy_serialize_get_struct_size (const guchar *object_name
,gsize nspec
,const GwySerializeSpec *spec
); gsize gwy_serialize_get_items_size (const guchar *object_name
,gsize nitems
,const GwySerializeItem *items
); 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
); gsize gwy_serialize_check_string (const guchar *buffer
,gsize size
,gsize position
,const guchar *compare_to
); 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
);
GwySerializable is an abstract interface for data-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()
and transform one object to
copy of another with gwy_serializable_clone()
.
Note all GwySerializable methods work with object `value', whatever it means
for a particular type. Beside that, objects also have their identity which
is unique and can't be subject of cloning. It consists of properties like
memory address or references held by object users. Two important properties
related to identity (and thus NOT retained) are: signals connected to
a particular object and user data set with g_object_set_data()
or
g_object_set_qdata()
.
You can implement serialization and deserialization in your classes with
gwy_serialize_pack_object_struct()
and gwy_serialize_unpack_object_struct()
or with 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. Serialized size calculations can be
in most cases performed by gwy_serialize_get_struct_size()
and
gwy_serialize_get_items_size()
helper functions.
GByteArray * (*GwySerializeFunc) (GObject *serializable
,GByteArray *buffer
);
The type of serialization method, see gwy_serializable_serialize()
for
description.
|
An object to serialize. |
|
A buffer to append the representation to, may be NULL indicating
a new one should be allocated. |
Returns : |
buffer with serialized object appended. |
GObject * (*GwyDeserializeFunc) (const guchar *buffer
,gsize size
,gsize *position
);
The type of deserialization method, see gwy_serializable_deserialize()
for
description.
|
A buffer containing a serialized object. |
|
The size of buffer . |
|
The current position in buffer . |
Returns : |
A newly created (restored) object. |
struct GwySerializableIface { GwySerializeFunc serialize; GwyDeserializeFunc deserialize; void (*clone)(GObject *source, GObject *copy); GObject* (*duplicate)(GObject *object); gsize (*get_size)(GObject *object); };
The methods a serializable objects has to implement.
GwySerializeFunc |
Serialization method (obligatory), see GwySerializeFunc for description. |
GwyDeserializeFunc |
Restore method (obligatory), see GwyDeserializeFunc for description. |
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. | |
Duplication method (optional). Creates a duplicate of an object. When it is absent, duplication is performed by a rather inefficient serialize-and-deserialize fallback. | |
Serialized size calculation method (optional). Calculates expected serialized object size (including object name and size header). Its purpose is to avoid frequent memory reallocations during serialization of large objects. The returned value may be inexact, a reasonable upper bound is sufficient. When it is absent, serialization is less efficient. |
typedef struct { guchar ctype; const guchar *name; gpointer value; guint32 *array_size; } GwySerializeSpec;
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.
Following atomic component types (ctype
's) exist:
'b'
for a boolean,
'c'
for a character,
'i'
for a 32bit integer,
'q'
for a 64bit integer,
'd'
for a gdouble,
's'
for a nul-terminated string,
'o'
for a serializable object.
And array component types:
'C'
for a character array,
'I'
for a 32bit integer array,
'Q'
for a 64bit integer array,
'D'
for a gdouble array,
'S'
for an array of nul-terminated strings,
'O'
for an array of objects.
guchar |
Component type, see description body for possible values. |
const guchar * |
Component name as a nul-terminated string. |
gpointer |
Pointer to component (always add one level of indirection; for
an object, a GObject** pointer should be stored). If it is
NULL , the component is ignored. For serialization it means it
is not serialized, for deserialization it means its existence
is acknowledged (no unknown component warning) but it's skipped
instead of unpacking. |
guint32 * |
Pointer to array size if component is an array, NULL
otherwise. |
typedef union { gboolean v_boolean; guchar v_char; guint32 v_int32; guint64 v_int64; gdouble v_double; guchar *v_string; GObject *v_object; gboolean *v_boolean_array; guchar *v_char_array; guint32 *v_int32_array; guint64 *v_int64_array; gdouble *v_double_array; guchar **v_string_array; GObject **v_object_array; } GwySerializeValue;
typedef struct { guchar ctype; const guchar *name; GwySerializeValue value; guint32 array_size; } GwySerializeItem;
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 |
Component type, see GwySerializeSpec for details. |
const guchar * |
Component name as a nul-terminated string. |
GwySerializeValue |
Component value. |
guint32 |
Array size if component is an array, unused otherwise. |
GByteArray * gwy_serializable_serialize (GObject *serializable
,GByteArray *buffer
);
Serializes an object to byte buffer.
This is a high-level method. Do not use it for implementation of child
object serialization (should you ever need to do it manually), it would
lead to repeated required buffer size calculations. In such a case, use
gwy_serializable_do_serialize()
FIXME: but that's not public.
|
A GObject that implements GwySerializable interface. |
|
A buffer to which the serialized object should be appended,
or NULL to allocate and return a new GByteArray. |
Returns : |
buffer or a newly allocated GByteArray with serialized
object appended. |
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.
|
A block of memory of size size contaning object representation. |
|
The size of buffer . |
|
The position of the object in buffer , it's updated to
point after it. |
Returns : |
A newly created object. |
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.
|
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. |
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).
|
An object implementing GwySerializable interface. |
|
An object of the same type as source to modify after it. |
gsize gwy_serializable_get_size (GObject *serializable
);
Calculates the expected size of serialized object.
|
A GObject that implements GwySerializable interface. |
Returns : |
The expected size of serialized serializable . |
gsize gwy_serialize_get_struct_size (const guchar *object_name
,gsize nspec
,const GwySerializeSpec *spec
);
Calculates serialized object size for struct-like objects.
The component specification is the same as in
gwy_serialize_pack_object_struct()
.
|
The type name of the object. |
|
The number of items in spec . |
|
The components to serialize. |
Returns : |
Serialized object size, it included space for object name and size. The value is exact unless some components are objects that do not return exact size estimate themselves. |
gsize gwy_serialize_get_items_size (const guchar *object_name
,gsize nitems
,const GwySerializeItem *items
);
Calculates serialized object size for hash-like objects.
The component specification is the same as in
gwy_serialize_object_items()
.
|
The type name of the object. |
|
The number of items items. |
|
The components to serialize. |
Returns : |
Serialized object size, it included space for object name and size. The value is exact unless some components are objects that do not return exact size estimate themselves. |
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):
1 2 3 4 5 6 7 8 9 10 11 12 13 14 |
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); } |
|
A buffer to which the serialized components should be appended. |
|
The type name of the object. |
|
The number of items in spec . |
|
The components to serialize. |
Returns : |
The buffer with serialization of spec components appended. |
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):
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 |
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); } |
|
A memory location containing a serialized object at position
position . |
|
Current size of buffer , new size is returned here. |
|
The position of the object in buffer , it's updated to point
after it. |
|
The type name of the object. |
|
The number of items in spec . |
|
The components to deserialize. |
Returns : |
Whether the unpacking succeeded (see description body for definition of success and failure). |
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.
|
A memory location containing a nul-terminated string at position
position . |
|
The size of buffer . |
|
The position of the string in buffer . |
|
String to compare buffer to, or NULL . |
Returns : |
The length of the nul-terminated string including the nul character; zero otherwise. |
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
.
|
A buffer to which the serialized components should be appended,
or NULL . |
|
The type of the object. |
|
The number of items items. |
|
The components to serialize. |
Returns : |
buffer or a newly allocated GByteArray with serialization of
items components appended. |
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.
|
A block of memory of size size contaning object representation. |
|
The size of buffer . |
|
Current position in buffer, will be updated to point after object. |
|
The type name of the object. |
|
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. |