DeeResourceManager

DeeResourceManager — Interface for classes that can serialize to and from GVariants

Synopsis

#include <dee.h>

struct              DeeResourceManagerIface;
gboolean            dee_resource_manager_store          (DeeResourceManager *self,
                                                         DeeSerializable *resource,
                                                         const gchar *resource_name,
                                                         GError **error);
GObject *           dee_resource_manager_load           (DeeResourceManager *self,
                                                         const gchar *resource_name,
                                                         GError **error);
DeeResourceManager *  dee_resource_manager_get_default  (void);

Description

Interface for classes that can serialize to and from GVariants.

There are two serialization concepts supported by this API: serialization and externalization. A serialized instance is created with dee_resource_manager_serialize() and can be read back with dee_resource_manager_parse() provided you know the correct GType for the serialized data. The GVariant representation of your serialized data is guaranteed to be exactly as you implement yourself in the serialize vfunc of the DeeResourceManagerIface.

With externalized instances you don't have to know the correct GType to recreate the instance. The GType is encoded in the data itself. When you're using dee_resource_manager_externalize() your data will be wrapped in a container format with the required object metadata to read it back. For this reason dee_resource_manager_parse_external() doesn't require you to pass in the GType you want to deserialize.

On Subclasses of DeeResourceManager Types

As a rule of thumb you need to re-implement the DeeResourceManager interface and install parse functions with dee_resource_manager_register_parser() every time you create a new class derived from a DeeResourceManager superclass.

In case a subclass does not provide it's own serialization interface Dee will recurse upwards in the type hierarchy and use the serialization and parser implementations of the first superclass with the required behaviour. This means that the parsed instance will not be an instance of the subclass but only of the resource_manager superclass. Caveat emptor.

Details

struct DeeResourceManagerIface

struct DeeResourceManagerIface {
  GTypeInterface g_iface;

  gboolean       (*store)         (DeeResourceManager  *self,
                                   DeeSerializable     *resource,
                                   const gchar         *resource_name,
                                   GError             **error);

  GObject*       (*load)          (DeeResourceManager  *self,
                                   const gchar         *resource_name,
                                   GError             **error);
};


dee_resource_manager_store ()

gboolean            dee_resource_manager_store          (DeeResourceManager *self,
                                                         DeeSerializable *resource,
                                                         const gchar *resource_name,
                                                         GError **error);

Store a resource under a given name. The resource manager must guarantee that the stored data survives system reboots and that you can recreate a copy of resource by calling dee_resource_manager_load() using the same resource_name.

Important note: This call may do blocking IO. The resource manager must guarantee that this call is reasonably fast, like writing the externalized resource to a file, but not blocking IO over a network socket.

self :

The resource manager to invoke

resource :

A DeeSerializable to store under resource_name. [transfer none]

resource_name :

The name to store the resource under. Will overwrite any existing resource with the same name

error :

A return location for a GError pointer. NULL to ignore errors

Returns :

TRUE on success and FALSE otherwise. In case of a runtime error the error pointer will point to a GError in the DeeResourceError domain.

dee_resource_manager_load ()

GObject *           dee_resource_manager_load           (DeeResourceManager *self,
                                                         const gchar *resource_name,
                                                         GError **error);

self :

The resource manager to invoke

resource_name :

The name of the resource to retrieve

error :

A return location for a GError pointer. NULL to ignore errors

Returns :

A newly allocated GObject in case of success and NULL otherwise. In case of a runtime error the error pointer will be point to a GError in the DeeResourceError domain. [transfer full]

dee_resource_manager_get_default ()

DeeResourceManager *  dee_resource_manager_get_default  (void);

Get a pointer to the platform default DeeResourceManager.

Returns :

. [transfer none]