Serializable boxed: Gwyddion Library Reference Manual

## Serializable boxed Serializable boxed — Making boxed types serialisable |

## Functions

gboolean | gwy_boxed_type_is_serializable ()
void | gwy_serializable_boxed_register_static ()
void | gwy_serializable_boxed_assign ()
gboolean | gwy_serializable_boxed_equal ()
gsize | gwy_serializable_boxed_n_items ()
GwySerializableGroup * | gwy_serializable_boxed_itemize ()
gpointer | gwy_serializable_boxed_construct ()

## Types and Values

| GwySerializableBoxedInfo

## Includes

    #include <libgwyddion/gwyddion.h>

## Description

The serialisable boxed protocol is an analogue of the serialisable object protocol described in section GwySerializable where more detailed discussion of the concept can be found. The protocol is intended for simple structs that do not do their own memory management and typically can be bitwise copied. Complex data should be represented as objects.

Boxed structs can be serialised as parts of objects. The top-level item of a serialised representation must be always an object. Also, serialisable boxed structs may contain only atomic types (FIXME: this is not enforced by the implementation at this moment).

## Functions

### gwy_boxed_type_is_serializable()

    gboolean
    gwy_boxed_type_is_serializable (GType type);

Determines if a type supports the boxed serialisable protocol.

#### Parameters

type | Type to query. Any GType may be given, not just boxed types. |

#### Returns

`TRUE` if `type` was registered as serialisable boxed type, `FALSE` if it was not.

### gwy_serializable_boxed_register_static()

    void
    gwy_serializable_boxed_register_static
                                   (GType type,
                                    const GwySerializableBoxedInfo *info);

Registers a serialisable boxed type.

A boxed type must be registered before it can be deserialised. Usually this function is called in `gwy_foo_get_type()` for the type although it is possible to register foreign boxed types as serialisable. They must be registered “soon enough” then.

Standard Gwyddion boxed serialisable types are registered by `gwy_type_init()`, i.e. at the very latest when deserialization is attempted.

#### Parameters

type | Boxed type to register as serialisable. |
info | Information how the type implements the serialization protocol. It is not not copied; hence `info` must be static data or allocated on heap and never freed. |

### gwy_serializable_boxed_assign()

    void
    gwy_serializable_boxed_assign (GType type,
                                   gpointer destination,
                                   gconstpointer source);

Copies the value of a boxed struct to another boxed struct.

#### Parameters

type | Type of `destination` and `source` . It must be a serialisable boxed type. |
destination | Pointer to boxed struct that should be made equal to `source` . |
source | Pointer to source boxed struct. |

### gwy_serializable_boxed_equal()

    gboolean
    gwy_serializable_boxed_equal (GType type,
                                  gconstpointer a,
                                  gconstpointer b);

Compares the values of two boxed structs for equality.

#### Parameters

type | Type of `a` and `b` . It must be a serialisable boxed type. |
a | Pointer to one boxed struct of type `type` . |
b | Pointer to another boxed struct of type `type` . |

#### Returns

`TRUE` if `a` and `b` are equal, `FALSE` if they differ.

### gwy_serializable_boxed_n_items()

    gsize
    gwy_serializable_boxed_n_items (GType type);

Obtains the number of items a boxed type serialises to.

#### Parameters

type | Serialisable boxed type. |

### gwy_serializable_boxed_itemize()

    GwySerializableGroup *
    gwy_serializable_boxed_itemize (GType type,
                                    gpointer boxed);

Creates the itemised representation of a serialisable boxed struct.

#### Parameters

type | Serialisable boxed type. |
boxed | Pointer to boxed struct of type `type` . |

#### Returns

Newly allocated itemised representation of `boxed` type components.

[transfer full]

### gwy_serializable_boxed_construct()

    gpointer
    gwy_serializable_boxed_construct (GType type,
                                      GwySerializableGroup *group,
                                      GwyErrorList **error_list);

Constructs a serialisable struct type from its itemised representation.

#### Parameters

type | Serialisable boxed type. |
group | List of items to construct the boxed struct from. |
error_list | Location to store the errors occuring, `NULL` to ignore. |

#### Returns

Newly allocated boxed type with the deserialised data, possibly `NULL` on fatal failure.

[transfer full]

## Types and Values

### GwySerializableBoxedInfo

    typedef struct {
        gsize      size;
        gsize      n_items;
        void     (*itemize)  (gpointer boxed,
                              GwySerializableGroup *items);
        gpointer (*construct)(GwySerializableGroup *items,
                              GwyErrorList **error_list);
        void     (*assign)   (gpointer destination,
                              gconstpointer source);
        gboolean (*equal)    (gconstpointer a,
                              gconstpointer b);
    } GwySerializableBoxedInfo;

Interface implemented by serialisable boxed types.

The fields and methods are similar to GwySerializableInterface where a more detailed discussion can be found. Some notes to the differences:

The number of items `n_items` is a constant, not a method, which is appropriate for plain old data. However, it is still an upper bound so you can actually serialise less items in `GwySerializableBoxedInfo.itemize()`. For the same reason, no equivalent of `GwySerializableInterface.done()` method exists.

Since a serialisable boxed type is a GBoxed, functions such as duplication are realised by the

GBoxed protocol, namely `g_boxed_copy()` and hence needs not be specified.

#### Members

gsize `size`; | Size of the boxed data for bit-wise operable plain old data. If it is non-zero `assign` and `equal` must be `NULL`; assignment and comparison is performed by direct memory copying and comparing. If it is zero these operation are performed usinng `assign` and `equal` that must be defined. |
gsize `n_items`; | Number of items the boxed struct serialises to. |
`itemize`() | Appends itemised representation of the boxed struct to the `items` list. |
`construct`() | Deserialises a boxed struct from array of itemised data. It returns a newly allocated boxed struct that must be freeable with `g_boxed_free()`. |
`assign`() | Makes the content of a boxed struct identical to the content of another boxed struct of the same type. If `size` is non-zero it can be `NULL`, meaning implicit bit-for-bit copy. |
`equal`() | Compares two boxed data for equality, returns `TRUE` if they are equal, `FALSE` if they differ. If `size` is non-zero it can be `NULL`, meaning implicit bit-for-bit comparison. |