GXmlSerializable

GXmlSerializable — Serialization framework. Base interface.

Functions

Types and Values

Description

Implementors of this interface, could define or override the way you want to represent your class in a XML file.

Functions

gxml_serializable_get_enable_unknown_serializable_property ()

gboolean
gxml_serializable_get_enable_unknown_serializable_property
                               (GXmlSerializable *self);

Return false if you want to ignore unknown properties and GXmlNode's not in your class definition.

Take care, disabling this feature you can lost data on serialization, because any unknown property or element will be discarted.

Parameters

self

the GXmlSerializable instance

 

gxml_serializable_set_default_namespace ()

gboolean
gxml_serializable_set_default_namespace
                               (GXmlSerializable *self,
                                GXmlNode *node);

Used to set specific namespace for an GXmlElement.

By default no namspace prefix is added to GXmlElement on serialized. Implementors must consider override this methodk if this node should have a namespace.

Parameters

self

the GXmlSerializable instance

 

node

 

 

gxml_serializable_serialize_use_xml_node_value ()

gboolean
gxml_serializable_serialize_use_xml_node_value
                               (GXmlSerializable *self);

Used to check GXmlElement's contents must be deseralized.

By default GXml's implementations doesn't deseriaze/serialize XML node contents. In order to enable it, you must override gxml_serializable_serialize_use_xml_node_value() method to return true and store XML node's content to "serialized-xml-node-value" property.

Implementors could set up methods to provide a clean easy to use API to set nodes contents. In most cases, users would like to set a value through a getter or setter or through a property in the class.

Parameters

self

the GXmlSerializable instance

 

gxml_serializable_node_name ()

gchar *
gxml_serializable_node_name (GXmlSerializable *self);

Defines the way to set Node name.

Parameters

self

the GXmlSerializable instance

 

gxml_serializable_property_use_nick ()

gboolean
gxml_serializable_property_use_nick (GXmlSerializable *self);

Defines the way to set Node's property name, by using it's nick instead of default name.

When serialize a class property, by default it uses its name given on class declaration, but is less common to see XML node properties with names like "your_property", but more common is to use "YourProperty". In order to use this kind of names, your implementation should use properties' nick name and override gxml_serializable_property_use_nick() method to return true. This should instruct your code to use this method to use property's nick name. This is the default in GXml default implementations.

Parameters

self

the GXmlSerializable instance

 

gxml_serializable_serialize ()

GXmlNode *
gxml_serializable_serialize (GXmlSerializable *self,
                             GXmlNode *node,
                             GError **error);

Serialize this object.

This method must call serialize_property() recursivally on all properties to serialize.

Parameters

self

the GXmlSerializable instance

 

node

 .

an GXmlNode object to serialize to.

.

[in]

error

location to store the error occuring, or NULL to ignore

 

gxml_serializable_serialize_property ()

GXmlNode *
gxml_serializable_serialize_property (GXmlSerializable *self,
                                      GXmlNode *element,
                                      GParamSpec *prop,
                                      GError **error);

Serialize a property prop on a GXmlElement.

This method is called recursivally by gxml_serializable_serialize() method over all properties to be serialized.

Parameters

self

the GXmlSerializable instance

 

element

 

 

prop

 

 

error

location to store the error occuring, or NULL to ignore

 

gxml_serializable_deserialize ()

gboolean
gxml_serializable_deserialize (GXmlSerializable *self,
                               GXmlNode *node,
                               GError **error);

Deserialize this object.

Parameters

self

the GXmlSerializable instance

 

node

 .

GXmlNode used to deserialize from.

.

[in]

error

location to store the error occuring, or NULL to ignore

 

gxml_serializable_deserialize_property ()

gboolean
gxml_serializable_deserialize_property
                               (GXmlSerializable *self,
                                GXmlNode *property_node,
                                GError **error);

Handles deserializing individual properties.

Interface method to handle deserialization of an individual property. The implementing class receives a description of the property and the GXmlNode that contains the content. The implementing GXmlSerializable object can extract the data from the GXmlNode and store it in its property itself. Note that the GXmlNode may be as simple as a GXmlText that stores the data as a string.

Implementors: Use Serializable.get_property_value in order to allow derived classes to override the properties to serialize.

Parameters

self

the GXmlSerializable instance

 

property_node

 .

the GXmlNode encapsulating data to deserialize

.

[in]

error

location to store the error occuring, or NULL to ignore

 

Returns

`true` if the property was handled.


gxml_serializable_find_property_spec ()

GParamSpec *
gxml_serializable_find_property_spec (GXmlSerializable *self,
                                      const gchar *property_name);

Handles finding the GParamSpec for a given property, it should a serializable property, see gxml_serializable_list_serializable_properties().

Parameters

self

the GXmlSerializable instance

 

property_name

 .

the name of a property to obtain a GParamSpec for

.

[in]

Returns

a GParamSpec describing the named property


gxml_serializable_default_find_property_spec ()

GParamSpec *
gxml_serializable_default_find_property_spec
                               (GXmlSerializable *self,
                                const gchar *property_name);

Default implementation for gxml_serializable_find_property_spec()

Parameters

self

the GXmlSerializable instance

 

property_name

 

 

gxml_serializable_list_serializable_properties ()

GParamSpec **
gxml_serializable_list_serializable_properties
                               (GXmlSerializable *self,
                                int *result_length1);

List the known properties for an object's class to be de/seriablizable.

Parameters

self

the GXmlSerializable instance

 

Returns

an array of GParamSpec of "properties" for the object.

.

[array length=result_length1]


gxml_serializable_default_list_serializable_properties ()

GParamSpec **
gxml_serializable_default_list_serializable_properties
                               (GXmlSerializable *self,
                                int *result_length1);

Default implementation for gxml_serializable_list_serializable_properties()

Parameters

self

the GXmlSerializable instance

 

Returns

.

[array length=result_length1]


gxml_serializable_get_unknown_serializable_properties ()

GeeMap *
gxml_serializable_get_unknown_serializable_properties
                               (GXmlSerializable *self);

Get and return the current value of the "unknown-serializable-properties" property.

On deserialization stores any GXmlAttribute not used on this object, but exists in current XML file.

Node's name is used as key to find stored GXmlAttribute, key is case sensitive.

XML allows great flexibility, providing different ways to represent the same information. This is a problem when you try to deserialize them.

In order to deserialize correctly, you must create your XML, both by serializing a GXmlSerializable object or by hand writing. By using the former, you can add extra information, like attributes, but most of them could be ignored or lost on deserialization/serialization process. To avoid data lost, you can override gxml_serializable_get_enable_unknown_serializable_property() method in order to return true, your implementation or the ones in GXml, will store all unknown attributes on deserialization and must serialize again back to the XML file. Even you are allowed to get this unknown objects by iterating on "unknown-serializable-properties" collection, if you know attribute's name, use it to retrieve it.

This property is ignored on serialisation.

Parameters

self

the GXmlSerializable instance to query

 

Returns

the value of the "unknown-serializable-properties" property


gxml_serializable_get_unknown_serializable_nodes ()

GeeCollection *
gxml_serializable_get_unknown_serializable_nodes
                               (GXmlSerializable *self);

Get and return the current value of the "unknown-serializable-nodes" property.

On deserialization stores any GXmlNode not used on this object, but exists in current XML file.

XML allows great flexibility, providing different ways to represent the same information. This is a problem when you try to deserialize them.

In order to deserialize correctly, you must create your XML, both by serializing a GXmlSerializable object or by hand writing. By using the former, you can add extra information, like nodes or contents in known nodes, but most of them could be ignored or lost on deserialization/serialization process. To avoid data lost, you can override gxml_serializable_get_enable_unknown_serializable_property() method in order to return true, your implementation or the ones in GXml, will store all unknown properties and nodes on deserialization and must serialize again back to the XML file. Even you are allowed to get this unknown objects by iterating on "unknown-serializable-nodes" hash table.

This property is ignored on serialisation.

Parameters

self

the GXmlSerializable instance to query

 

Returns

the value of the "unknown-serializable-nodes" property


gxml_serializable_get_serialized_xml_node_value ()

gchar *
gxml_serializable_get_serialized_xml_node_value
                               (GXmlSerializable *self);

Get and return the current value of the "serialized-xml-node-value" property.

Used to add content in an GXmlElement.

By default no contents is serialized/deseralized. Implementors must implement gxml_serializable_serialize_use_xml_node_value() function returning true in order to use this property.

This property is ignored by default. Implementors must implement gxml_serializable_serialize_use_xml_node_value() to return true and add a set and get function to get/set this value, in order to use your own API.

This property is ignored on serialisation.

Parameters

self

the GXmlSerializable instance to query

 

Returns

the value of the "serialized-xml-node-value" property


gxml_serializable_set_serialized_xml_node_value ()

void
gxml_serializable_set_serialized_xml_node_value
                               (GXmlSerializable *self,
                                const gchar *value);

Set the value of the "serialized-xml-node-value" property to value .

Used to add content in an GXmlElement.

By default no contents is serialized/deseralized. Implementors must implement gxml_serializable_serialize_use_xml_node_value() function returning true in order to use this property.

This property is ignored by default. Implementors must implement gxml_serializable_serialize_use_xml_node_value() to return true and add a set and get function to get/set this value, in order to use your own API.

This property is ignored on serialisation.

Parameters

self

the GXmlSerializable instance to modify

 

value

the new value of the "serialized-xml-node-value" property

 

gxml_serializable_string_to_gvalue ()

gboolean
gxml_serializable_string_to_gvalue (const gchar *str,
                                    GValue *dest,
                                    GError **error);

Transforms a string into another type hosted by GValue.

A utility function that handles converting a string representation of a value into the type specified by the supplied GValue dest. A GXmlSerializableError will be set if the string cannot be parsed into the desired type.

GXmlSerializable interface support a number of data types to convert from its string representation. These are supported types:

a. integers: int8, int64, uint, long, ulong, char, uchar a. boolean a. floats: float, double a. enumerations

Parameters

str

 .

the string to transform into the given GValue object

.

[in]

dest

 .

the GValue out parameter that will contain the parsed value from the string

.

[inout]

error

location to store the error occuring, or NULL to ignore.

[error-domains GXmlSerializableError]

Returns

`true` if parsing succeeded, otherwise `false`


gxml_serializable_gvalue_to_string ()

gchar *
gxml_serializable_gvalue_to_string (GValue *val,
                                    GError **error);

Transforms a GValue to its string representation.

By default use GValue standard transformations.

Parameters

val

 

 

error

location to store the error occuring, or NULL to ignore.

[error-domains GXmlSerializableError]

Types and Values

enum GXmlSerializableError

Errors from GXmlSerializable.

Members

GXML_SERIALIZABLE_ERROR_UNSUPPORTED_TYPE_ERROR

An object with a known GType that we do not support was encountered.

 

GXML_SERIALIZABLE_ERROR_STR_TO_VALUE_ERROR

   

GXmlSerializable

typedef struct _GXmlSerializable GXmlSerializable;

Serialization framework. Base interface.

Implementors of this interface, could define or override the way you want to represent your class in a XML file.


struct GXmlSerializableIface

struct GXmlSerializableIface {
	GTypeInterface parent_iface;
	gboolean (*get_enable_unknown_serializable_property) (GXmlSerializable* self);
	gboolean (*set_default_namespace) (GXmlSerializable* self, GXmlNode* node);
	gboolean (*serialize_use_xml_node_value) (GXmlSerializable* self);
	gchar* (*node_name) (GXmlSerializable* self);
	gboolean (*property_use_nick) (GXmlSerializable* self);
	GXmlNode* (*serialize) (GXmlSerializable* self, GXmlNode* node, GError** error);
	GXmlNode* (*serialize_property) (GXmlSerializable* self, GXmlNode* element, GParamSpec* prop, GError** error);
	gboolean (*deserialize) (GXmlSerializable* self, GXmlNode* node, GError** error);
	gboolean (*deserialize_property) (GXmlSerializable* self, GXmlNode* property_node, GError** error);
	GParamSpec* (*find_property_spec) (GXmlSerializable* self, const gchar* property_name);
	GParamSpec* (*default_find_property_spec) (GXmlSerializable* self, const gchar* property_name);
	GParamSpec** (*list_serializable_properties) (GXmlSerializable* self, int* result_length1);
	GParamSpec** (*default_list_serializable_properties) (GXmlSerializable* self, int* result_length1);
	GeeMap* (*get_unknown_serializable_properties) (GXmlSerializable* self);
	GeeCollection* (*get_unknown_serializable_nodes) (GXmlSerializable* self);
	gchar* (*get_serialized_xml_node_value) (GXmlSerializable* self);
	void (*set_serialized_xml_node_value) (GXmlSerializable* self, const gchar* value);
};

Interface for creating GXmlSerializable implementations.

Members

GTypeInterface parent_iface;

the parent interface structure

 

get_enable_unknown_serializable_property ()

virtual method called by gxml_serializable_get_enable_unknown_serializable_property()

 

set_default_namespace ()

virtual method called by gxml_serializable_set_default_namespace()

 

serialize_use_xml_node_value ()

virtual method called by gxml_serializable_serialize_use_xml_node_value()

 

node_name ()

virtual method called by gxml_serializable_node_name()

 

property_use_nick ()

virtual method called by gxml_serializable_property_use_nick()

 

serialize ()

virtual method called by gxml_serializable_serialize()

 

serialize_property ()

virtual method called by gxml_serializable_serialize_property()

 

deserialize ()

virtual method called by gxml_serializable_deserialize()

 

deserialize_property ()

virtual method called by gxml_serializable_deserialize_property()

 

find_property_spec ()

virtual method called by gxml_serializable_find_property_spec()

 

default_find_property_spec ()

virtual method called by gxml_serializable_default_find_property_spec()

 

list_serializable_properties ()

virtual method called by gxml_serializable_list_serializable_properties()

 

default_list_serializable_properties ()

virtual method called by gxml_serializable_default_list_serializable_properties()

 

get_unknown_serializable_properties ()

getter method for the abstract property "unknown-serializable-properties"

 

get_unknown_serializable_nodes ()

getter method for the abstract property "unknown-serializable-nodes"

 

get_serialized_xml_node_value ()

getter method for the abstract property "serialized-xml-node-value"

 

set_serialized_xml_node_value ()

setter method for the abstract property "serialized-xml-node-value"