Serialize: Gwyddion Library Reference Manual

## Serialize Serialize — Object serialisation |

## Functions

gboolean | gwy_serialize_gio ()
gboolean | gwy_serialize_group_gio ()

## 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_serialize_gio()` to directly write serialised object data. For version 2, you can use `gwy_serialize_group_gio()` with `GWY_SERIALIZE_SIZE_32BIT` to write the intermediate representation, but as the object differ, the intermediate representation needs to be created manually.

### Details of Serialization

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 occurs in several steps.

First, all objects are recursively asked to represent themselves as GwySerializableGroup, which is a list of items. The groups can contain nested groups in `v_group` item values to represent object- and boxed-valued components. The creation of the items may require the allocation of temporary data structures, if the internal object representation does not match the serialised representation. This step is independent on the serialisation backend format.

Second, the top-level group is written to the output stream, recusring to contiained groups, byte-swapping or otherwise normalizing the data on the fly if necessary. This part strongly depends on the storage format.

Finally, virtual method `done()` is called on all objects in the tree which define it. This step frees the temporary storage allocated in the itemisation step, if any. It is done in reverse order of which the objects have been serialised, although this should not matter. The serialiser does the recursion. Hence, objects do not need to implement `done()` if do not needed themselves but some of their member objects might. At the very end the groups are freed too.

## Functions

### gwy_serialize_gio()

    gboolean
    gwy_serialize_gio (GwySerializable *serializable,
                       GOutputStream *output,
                       GError **error);

Serialises an object to GIO stream in GWY format.

The data writing employs internal buffering. If the output stream is already buffered (e.g., GBufferedOutputStream), the output will be unnecessarily buffered twice.

#### Parameters

serializable | A serialisable object. |
output | Output stream to write the serialised object to. |
error | Location to store the error occuring, `NULL` to ignore. Errors from `G_IO_ERROR` domain can occur. |

#### Returns

`TRUE` if the operation succeeded, `FALSE` if it failed.

### gwy_serialize_group_gio()

    gboolean
    gwy_serialize_group_gio (GwySerializableGroup *group,
                             GwySerializeSizeType sizetype,
                             GOutputStream *output,
                             GError **error);

Serialises itemised data to GIO stream in GWY format.

This is low-level function, mean when `group` was created or modified manually or the itemisation was run separately for some other reason. Use `gwy_serialize_gio()` for normal object serialisation. Remember to call `gwy_serializable_group_done()` on the group and `gwy_serializable_done()` on the top-level object if needed. This function only carries out the serialisation to an output stream.

The data writing employs internal buffering. If the output stream is already buffered (e.g., GBufferedOutputStream), the output will be unnecessarily buffered twice.

#### Parameters

group | Itemised object components. |
sizetype | Type of size representation. |
output | Output stream to write the serialised object to. |
error | Location to store the error occuring, `NULL` to ignore. Errors from `G_IO_ERROR` domain can occur. |

#### Returns

`TRUE` if the operation succeeded, `FALSE` if it failed.