Deserialise: Gwyddion Library Reference Manual

## Deserialise Deserialise — Object deserialisation |

## Functions

GObject * | gwy_deserialize_memory ()
GwySerializableGroup * | gwy_deserialize_group_memory ()
GObject * | gwy_deserialize_construct ()

## Includes

    #include <libgwyddion/gwyddion.h>

## Description

Functions available here implement the GWY binary data format, version 3. Some low-level facilities for version 2 format are also provided. Essentially, for version 3, you can use `gwy_deserialize_memory()` to directly construct objects. For version 2, you can use `gwy_deserialize_group_memory()` with `GWY_SERIALIZE_SIZE_32BIT` to construct the intermediate representation, but not objects directly (since they in general differ).

### Details of Deserialization

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 has two basic steps.

First, the serialised buffer is parse into a tree of GwySerializableGroup, using `v_group` for nested objects. This step checks basic validity of the serialised representation. If it succeeds, the GwySerializableGroup tree is well-formed, although it may not represent valid Gwyddion object data. If only this step is run, it can also be used to represent other things than Gwyddion files. This is also the only backend-depndent step which would be implemented differently for HDF5 as the serialisation format, for instance.

Second, objects are reconstructed from the tree in a depth-first order. When an object's GwySerializable `construct()` method is called, its object- and boxed-valued components have already been constructed and it can get them by reading `v_object` or `v_boxed` values of GwySerializableValue.

There is also some cleanup. But it is done during the second step, not as a separate pass.

## Functions

### gwy_deserialize_memory()

    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.

The initial references 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.

Deserialization sidesteps the typical object creation somewhat. It needs to construct an object given its class name, and for that the type has to be already registered in the GObject type system. Library initialisation functions such as `gwy_init()` or `gwy_app_init()` normally take care of it. If you introduce your own serialisable objects (or avoid the initialisation functions for some reason), force the registration of all relevant types for instance by calling g_type_class_peak(MY_TYPE_WHATEVER).

Errors from `GWY_DESERIALIZE_ERROR` domain can always occur in `error_list` . For most objects, these are the only errors that can occur. However, special objects can report more specific non-fatal errors from their own domain. For example, GwyFile does.

#### Parameters

buffer | Memory containing the serialised representation of one object. |
size | Size of `buffer` in bytes. If the buffer is larger than the object representation, non-fatal `GWY_DESERIALIZE_ERROR_PADDING` will be reported. |
bytes_consumed | Location to store the number of bytes actually consumed from `buffer` , or `NULL`. | [nullable]
error_list | Location to store the errors occuring, `NULL` to ignore. | [nullable]

#### Returns

Newly created object on success, `NULL` on failure.

[transfer full][allow-none]

### gwy_deserialize_group_memory()

    GwySerializableGroup *
    gwy_deserialize_group_memory (const guchar *buffer,
                                  gsize size,
                                  GwySerializeSizeType sizetype,
                                  GwyErrorList **error_list);

Deserialises GWY format from plain memory buffer to itemised representation.

This is a low-level function. Usually, you use a function such as `gwy_deserialize_memory()` to immediately construct the object. For this function, the serialised data must be well-formed but are not required to represent actual Gwyddion objects. This is only required when objects are constructed from the itemised representation – which can, however, be used for other purposes if needed.

The number of bytes consumed can be obtained by looking at the byte size of the returned group.

Object and item names (and possibly other data as well) in the returned group can simply be pointers inside `buffer` . Therefore, `buffer` must outlive the group.

#### Parameters

buffer | Memory containing the serialised representation of one object. |
size | Size of `buffer` in bytes. If the buffer is larger than the object representation, non-fatal `GWY_DESERIALIZE_ERROR_PADDING` will be reported. |
sizetype | Type of size representation. |
error_list | Location to store the errors occuring, `NULL` to ignore. Only errors from `GWY_DESERIALIZE_ERROR` domain can occur. | [nullable]

#### Returns

Newly created group corresponding to the top-level object, `NULL` on failure.

[transfer full][allow-none]

### gwy_deserialize_construct()

    GObject *
    gwy_deserialize_construct (GwySerializableGroup *group,
                               GwyErrorList **error_list);

Creates an object from itemised representation.

This is a low-level function. Usually, you use a function such as `gwy_deserialize_memory()` to immediately construct the object.

The initial references 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.

#### Parameters

group | Itemised object components. The contents of `group` is consumed by the deserialisation and it is freed. | [transfer full]
error_list | Location to store the errors occuring, `NULL` to ignore. Errors from `GWY_DESERIALIZE_ERROR` domain can occur. | [nullable]

#### Returns

Newly created object on success, `NULL` on failure.

[transfer full][allow-none]