![]() |
![]() |
Gwyddion Library Reference Manual | ![]() |
|
---|---|---|---|---|
GwySerializableIface; GwySerializable; GByteArray* (*GwySerializeFunc) (GObject *serializable, GByteArray *buffer); GObject* (*GwyDeserializeFunc) (const guchar *buffer, gsize size, gsize *position); GObject* (*GwyDuplicateFunc) (GObject *object); GwySerializeSpec; 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); GByteArray* gwy_serialize_pack (GByteArray *buffer, const gchar *templ, ...); void gwy_serialize_store_int32 (GByteArray *buffer, gsize position, guint32 value); 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); 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 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.
typedef struct { GTypeInterface parent_class; GwySerializeFunc serialize; GwyDeserializeFunc deserialize; GwyDuplicateFunc duplicate; } GwySerializableIface;
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.
|
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. |
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 .
|
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.
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. |
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 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. |
Since 1.7
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 GByteArray with serialized
object appended.
|
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. |
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.
|
GByteArray* gwy_serialize_pack (GByteArray *buffer, const gchar *templ, ...);
gwy_serialize_pack
is deprecated and should not be used in newly-written code.
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 gdouble, '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 gdouble array.
'o' for a serializable object.
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.
|
void gwy_serialize_store_int32 (GByteArray *buffer, gsize position, guint32 value);
gwy_serialize_store_int32
is deprecated and should not be used in newly-written code.
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. |
gboolean gwy_serialize_unpack_boolean (const guchar *buffer, gsize size, gsize *position);
gwy_serialize_unpack_boolean
is deprecated and should not be used in newly-written code.
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. |
guchar gwy_serialize_unpack_char (const guchar *buffer, gsize size, gsize *position);
gwy_serialize_unpack_char
is deprecated and should not be used in newly-written code.
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. |
guchar* gwy_serialize_unpack_char_array (const guchar *buffer, gsize size, gsize *position, gsize *asize);
gwy_serialize_unpack_char_array
is deprecated and should not be used in newly-written code.
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 on success. |
Returns : | The unpacked character array (newly allocated). |
gint32 gwy_serialize_unpack_int32 (const guchar *buffer, gsize size, gsize *position);
gwy_serialize_unpack_int32
is deprecated and should not be used in newly-written code.
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. |
gint32* gwy_serialize_unpack_int32_array (const guchar *buffer, gsize size, gsize *position, gsize *asize);
gwy_serialize_unpack_int32_array
is deprecated and should not be used in newly-written code.
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 on success. |
Returns : | The unpacked 32bit integer array (newly allocated). |
gint64 gwy_serialize_unpack_int64 (const guchar *buffer, gsize size, gsize *position);
gwy_serialize_unpack_int64
is deprecated and should not be used in newly-written code.
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. |
gint64* gwy_serialize_unpack_int64_array (const guchar *buffer, gsize size, gsize *position, gsize *asize);
gwy_serialize_unpack_int64_array
is deprecated and should not be used in newly-written code.
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 on success. |
Returns : | The unpacked 64bit integer array (newly allocated). |
gdouble gwy_serialize_unpack_double (const guchar *buffer, gsize size, gsize *position);
gwy_serialize_unpack_double
is deprecated and should not be used in newly-written code.
Deserializes a one gdouble.
buffer : |
A memory location containing a serialized gdouble 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. |
gdouble* gwy_serialize_unpack_double_array (const guchar *buffer, gsize size, gsize *position, gsize *asize);
gwy_serialize_unpack_double_array
is deprecated and should not be used in newly-written code.
Deserializes a gdouble array.
buffer : |
A memory location containing a serialized gdouble 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 on success. |
Returns : | The unpacked gdouble array (newly allocated). |
guchar* gwy_serialize_unpack_string (const guchar *buffer, gsize size, gsize *position);
gwy_serialize_unpack_string
is deprecated and should not be used in newly-written code.
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. |
gsize gwy_serialize_check_string (const guchar *buffer, gsize size, gsize position, const guchar *compare_to);
gwy_serialize_check_string
is deprecated and should not be used in newly-written code.
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. |
GByteArray* gwy_serialize_pack_struct (GByteArray *buffer, gsize nspec, const GwySerializeSpec *spec);
gwy_serialize_pack_struct
is deprecated and should not be used in newly-written code.
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.
|
gboolean gwy_serialize_unpack_struct (const guchar *buffer, gsize size, gsize nspec, const GwySerializeSpec *spec);
gwy_serialize_unpack_struct
is deprecated and should not be used in newly-written code.
Deserializes a structure with named components packed by
gwy_serialize_pack_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.
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). |
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.
|
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 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). |
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.
|
Since 1.7
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.
|
Since 1.7