IpatchXmlObject

IpatchXmlObject — GObject encoding/decoding related XML tree functions

Stability Level

Stable, unless otherwise indicated

Functions

Description

introduction This module provides functions for saving/loading whole GObject properties, single GObject property and single GValue to/from XML trees.

The module includes also a system for registering custom encoding and decoding handlers for objects properties, single property and single Galue types (see 1). Custom XML encoding handler will be used when saving to XML trees (see 2). Conversely custom XML decoding handler will be used when loading from XML trees (see 3).

Functions presentation 1) registering system for encoding/decoding handlers: 1.1)First we create an internal table (xml_handlers) that will be used to register custom encoding/decoding XML handlers. This table is created by _ipatch_xml_object_init() during libinstpatch initialization (ipatch_init()) and is owned by libinstpatch.

1.2)Then if the application need custom encoding/decoding XML handlers it must call ipatch_xml_register_handler(). Once handlers are registered, they will be called automatically when the application will use functions to save (see 2) or load (see 3) gobjet properties, a single property or a single GValue to/from XML tree. Note that if a custom handlers doesn't exist a default handler will be used instead.

1.3)Any custom handlers may be looked by calling patch_xml_lookup_handler(), patch_xml_lookup_handler_by_prop_name()

2)Functions for encoding (saving) whole object properties, single GObject property or single GValue to an XML tree node:

2.1) To save a whole object to an XML tree node, the application must call ipatch_xml_encode_object(node, object). It is maily intended to save many properties values belonging to the given object. Which properties are saved depends of the behaviour of custom encoding handlers registered (if any). Default encoding handler save all properties's value (except those which have the IPATCH_PARAM_NO_SAVE flag set.

2.1) To save a single property object to an XML tree node, the application must call ipatch_xml_encode_property(node, object, pspec) or ipatch_xml_encode_property_by_name(node, object, propname).

2.2) To save a single GValue value to an XML tree node, the application must call ipatch_xml_encode_value (node, value).

3)Functions for decoding (loading) whole object, single GObject property or single GValue from an XML tree node:

3.1) To load a whole object from an XML tree node, the application must call ipatch_xml_decode_object(node, object). It is maily intended to load many properties values belonging to the given object. Which properties are loaded depends of the behaviour of custom decoding handlers registered (if any). Default decoding handler load all properties's value (except those which have the IPATCH_PARAM_NO_SAVE flag set.

3.1) To load a single property object from an XML tree node, the application must call ipatch_xml_decode_property(node, object, pspec) or ipatch_xml_decode_property_by_name(node, object, propname).

3.2) To load a single GValue value from an XML tree node, the application must call ipatch_xml_decode_value (node, value).

Functions

IpatchXmlEncodeFunc ()

gboolean
(*IpatchXmlEncodeFunc) (GNode *node,
                        GObject *object,
                        GParamSpec *pspec,
                        GValue *value,
                        GError **err);

Function type for encoding objects, properties or GValue types to XML trees. Forms the basis of serializing GObject and GValues to XML. The caller handles creating an XML node element to contain the given object, property or value XML encoding.

Parameters

node

XML node to encode XML to

 

object

Object being encoded (object and property encoders)

 

pspec

Spec of property being encoded (property encoders only)

 

value

Value to encode (property and GValue encoders only)

 

err

Location to store error value (or NULL if ignoring)

 

Returns

Should return TRUE on success and FALSE on error (in which case err should be set).


IpatchXmlDecodeFunc ()

gboolean
(*IpatchXmlDecodeFunc) (GNode *node,
                        GObject *object,
                        GParamSpec *pspec,
                        GValue *value,
                        GError **err);

Function type for decoding objects, properties or GValue types from XML trees to their original instance values in memory. For object decoders, only object will be set and the decoded XML content should be assigned to the object; for property decoders object , pspec and value will be set, value is initialized to the property value type and the decoded value should be assigned to it; for GValue decoders, only the value will be initialized which the decoded value should be assigned to.

Parameters

node

XML node to be decoded

 

object

Object being decoded to (object and property decoders, NULL otherwise)

 

pspec

Spec of property being decoded (property decoders only, NULL otherwise)

 

value

Value to decode to (property and GValue decoders only, NULL otherwise)

 

err

Location to store error value (or NULL if ignoring)

 

Returns

Should return TRUE on success, FALSE otherwise (in which case err should be set)


ipatch_xml_register_handler ()

void
ipatch_xml_register_handler (GType type,
                             const char *prop_name,
                             IpatchXmlEncodeFunc encode_func,
                             IpatchXmlDecodeFunc decode_func);

Registers XML encoding/decoding handlers for a GObject type, GObject property or GValue type.

[skip]

Parameters

type

GType to register handler functions for (GObject type if an object or object property handler, GValue type for value handlers).

 

prop_name

GObject property name (or NULL if not a GObject property handler)

 

encode_func

Function to handle encoding (object/property/value -> XML)

 

decode_func

Function to handle decoding (XML -> object/property/value)

 

ipatch_xml_register_handler_full ()

void
ipatch_xml_register_handler_full (GType type,
                                  const char *prop_name,
                                  IpatchXmlEncodeFunc encode_func,
                                  IpatchXmlDecodeFunc decode_func,
                                  GDestroyNotify notify_func,
                                  gpointer user_data);

Registers XML encoding/decoding handlers for a GObject type, GObject property or GValue type.

[rename-to ipatch_xml_register_handler]

Parameters

type

GType to register handler functions for (GObject type if an object or object property handler, GValue type for value handlers).

 

prop_name

GObject property name (or NULL if not a GObject property handler).

[nullable]

encode_func

Function to handle encoding (object/property/value -> XML).

[scope notified]

decode_func

Function to handle decoding (XML -> object/property/value).

[scope notified]

notify_func

Callback when handlers are removed.

[nullable][scope async][closure user_data]

user_data

Data passed to notify_func .

[nullable]

Since: 1.1.0


ipatch_xml_lookup_handler ()

gboolean
ipatch_xml_lookup_handler (GType type,
                           GParamSpec *pspec,
                           IpatchXmlEncodeFunc *encode_func,
                           IpatchXmlDecodeFunc *decode_func);

Looks up handlers for a given GObject type, GObject property or GValue type previously registered with ipatch_xml_register_handler(). These functions are used for encoding/decoding to/from XML.

[skip]

Parameters

type

GObject or GValue type of handler to lookup

 

pspec

GObject property spec (or NULL if not a GObject property handler).

[nullable]

encode_func

Location to store encoding function (or NULL to ignore).

[out][optional]

decode_func

Location to store decoding function (or NULL to ignore).

[out][optional]

Returns

TRUE if handler found, FALSE otherwise


ipatch_xml_lookup_handler_by_prop_name ()

gboolean
ipatch_xml_lookup_handler_by_prop_name
                               (GType type,
                                const char *prop_name,
                                IpatchXmlEncodeFunc *encode_func,
                                IpatchXmlDecodeFunc *decode_func);

Like ipatch_xml_lookup_handler() but takes a prop_name string to indicate which GObject property to lookup instead of a GParamSpec.

[skip]

Parameters

type

GObject or GValue type of handler to lookup

 

prop_name

GObject property name (or NULL if not a GObject property handler).

[nullable]

encode_func

Location to store encoding function (or NULL to ignore).

[out][optional]

decode_func

Location to store decoding function (or NULL to ignore).

[out][optional]

Returns

TRUE if handler found, FALSE otherwise


ipatch_xml_encode_object ()

gboolean
ipatch_xml_encode_object (GNode *node,
                          GObject *object,
                          gboolean create_element,
                          GError **err);

Encodes an object to XML. It there is no encoder for this object a default encoder ipatch_xml_default_encode_object_func() will be used instead.

Parameters

node

XML node to encode to

 

object

Object to encode to XML

 

create_element

TRUE to create a <obj> element, FALSE to add object properties to current open element

 

err

Location to store error info or NULL to ignore

 

Returns

TRUE on success, FALSE otherwise (in which case err may be set).


ipatch_xml_encode_property ()

gboolean
ipatch_xml_encode_property (GNode *node,
                            GObject *object,
                            GParamSpec *pspec,
                            gboolean create_element,
                            GError **err);

Encode an object property value to an XML node. If there is no encoder for this property, the function ipatch_xml_encode_value() will be used instead.

Parameters

node

XML node to encode to

 

object

GObject to encode property of

 

pspec

Parameter specification of property to encode

 

create_element

TRUE to create a <prop name="PROPNAME"> element, FALSE to assign object property value to node

 

err

Location to store error info or NULL to ignore

 

Returns

TRUE on success, FALSE otherwise


ipatch_xml_encode_property_by_name ()

gboolean
ipatch_xml_encode_property_by_name (GNode *node,
                                    GObject *object,
                                    const char *propname,
                                    gboolean create_element,
                                    GError **err);

Encode an object property by name to an XML node. Like ipatch_xml_encode_property() but takes a propname string instead of a GParamSpec.

Parameters

node

XML node to encode to

 

object

GObject to encode property of

 

propname

Name of object property to encode

 

create_element

TRUE to create a <prop name="PROPNAME"> element, FALSE to assign object property value to node

 

err

Location to store error info or NULL to ignore

 

Returns

TRUE on success, FALSE otherwise


ipatch_xml_encode_value ()

gboolean
ipatch_xml_encode_value (GNode *node,
                         GValue *value,
                         GError **err);

Encodes a GValue to an XML node text value. If there is not encoder for this GValue, ipatch_xml_default_encode_value_func() default encoder will be used instead.

Parameters

node

XML node to encode to

 

value

Value to encode

 

err

Location to store error info or NULL to ignore

 

Returns

TRUE on success, FALSE on error (err may be set)


ipatch_xml_decode_object ()

gboolean
ipatch_xml_decode_object (GNode *node,
                          GObject *object,
                          GError **err);

Decodes XML to an object. If there is no decoder for this object, the default GObject decoder ipatch_xml_default_decode_object_func() will be used and will only decode those properties which don't have the IPATCH_PARAM_NO_SAVE flag set.

Parameters

node

XML node to decode from

 

object

Object to decode to from XML

 

err

Location to store error info or NULL to ignore

 

Returns

TRUE on success, FALSE otherwise (in which case err may be set).


ipatch_xml_decode_property ()

gboolean
ipatch_xml_decode_property (GNode *node,
                            GObject *object,
                            GParamSpec *pspec,
                            GError **err);

Decode an object property from an XML node value to an object. If there is no decoder for this property, ipatch_xml_decode_value() function will be used instead. The property is NOT checked for the IPATCH_PARAM_NO_SAVE flag.

Parameters

node

XML node to decode from

 

object

GObject to decode property of

 

pspec

Parameter specification of property to decode

 

err

Location to store error info or NULL to ignore

 

Returns

TRUE on success, FALSE otherwise


ipatch_xml_decode_property_by_name ()

gboolean
ipatch_xml_decode_property_by_name (GNode *node,
                                    GObject *object,
                                    const char *propname,
                                    GError **err);

Decode an object property from an XML node value to an object by property name. Like ipatch_xml_decode_property() but but takes a propname string instead of a GParamSpec. Note that the property is NOT checked for the IPATCH_PARAM_NO_SAVE flag.

Parameters

node

XML node to decode from

 

object

GObject to decode property of

 

propname

Name of object property to decode

 

err

Location to store error info or NULL to ignore

 

Returns

TRUE on success, FALSE otherwise


ipatch_xml_decode_value ()

gboolean
ipatch_xml_decode_value (GNode *node,
                         GValue *value,
                         GError **err);

Decodes a GValue from an XML node text value.

Parameters

node

XML node to decode from

 

value

Value to decode to

 

err

Location to store error info or NULL to ignore

 

Returns

TRUE on success, FALSE on error (err may be set)


ipatch_xml_default_encode_object_func ()

gboolean
ipatch_xml_default_encode_object_func (GNode *node,
                                       GObject *object,
                                       GParamSpec *pspec,
                                       GValue *value,
                                       GError **err);

Default GObject encode handler. Useful to chain to the default if custom object handler doesn't exist. All properties belonging to object are encoded except those which have the * IPATCH_PARAM_NO_SAVE flag set.

[type IpatchXmlEncodeFunc]

Parameters

node

XML node to encode XML to

 

object

Object to encode

 

pspec

Will be NULL

 

value

Will be NULL

 

err

Location to store error value (or NULL if ignoring)

 

Returns

TRUE on success, FALSE on error (err may be set)


ipatch_xml_default_encode_property_func ()

gboolean
ipatch_xml_default_encode_property_func
                               (GNode *node,
                                GObject *object,
                                GParamSpec *pspec,
                                GValue *value,
                                GError **err);

Default GObject property encode handler. Useful for custom handlers to chain to the default if needed.

[type IpatchXmlEncodeFunc]

Parameters

node

XML node to encode XML to

 

object

Object to encode

 

pspec

Parameter spec of property to encode

 

value

Value of the property

 

err

Location to store error value (or NULL if ignoring)

 

Returns

TRUE on success, FALSE on error (err may be set)


ipatch_xml_default_encode_value_func ()

gboolean
ipatch_xml_default_encode_value_func (GNode *node,
                                      GObject *object,
                                      GParamSpec *pspec,
                                      GValue *value,
                                      GError **err);

Default GValue encode handler. Useful to chain to the default when custom GValue encoder doesn't exist.

[type IpatchXmlEncodeFunc]

Parameters

node

XML node to encode XML to

 

object

Will be NULL

 

pspec

Will be NULL

 

value

Value to encode

 

err

Location to store error value (or NULL if ignoring)

 

Returns

TRUE on success, FALSE on error (err may be set)


ipatch_xml_default_decode_object_func ()

gboolean
ipatch_xml_default_decode_object_func (GNode *node,
                                       GObject *object,
                                       GParamSpec *pspec,
                                       GValue *value,
                                       GError **err);

Default GObject decode handler. Useful for custom handlers to chain to the default if needed.

[type IpatchXmlDecodeFunc]

Parameters

node

XML node to decode XML from

 

object

Object to decode to

 

pspec

Will be NULL

 

value

Will be NULL

 

err

Location to store error value (or NULL if ignoring)

 

Returns

TRUE on success, FALSE on error (err may be set)


ipatch_xml_default_decode_property_func ()

gboolean
ipatch_xml_default_decode_property_func
                               (GNode *node,
                                GObject *object,
                                GParamSpec *pspec,
                                GValue *value,
                                GError **err);

Default GObject property decode handler. Useful to chain to the default if custom property handler doesn't exist.

[type IpatchXmlDecodeFunc]

Parameters

node

XML node to decode XML from

 

object

Object whose property is being decoded

 

pspec

Parameter spec of property to decode

 

value

Initialized value to decode to

 

err

Location to store error value (or NULL if ignoring)

 

Returns

TRUE on success, FALSE on error (err may be set)


ipatch_xml_default_decode_value_func ()

gboolean
ipatch_xml_default_decode_value_func (GNode *node,
                                      GObject *object,
                                      GParamSpec *pspec,
                                      GValue *value,
                                      GError **err);

Default GObject GValue decode handler. Useful to chain to the default if custom GValue handler doesn't exist.

[type IpatchXmlDecodeFunc]

Parameters

node

XML node to decode XML from

 

object

Will be NULL

 

pspec

Will be NULL

 

value

Value to decode to

 

err

Location to store error value (or NULL if ignoring)

 

Returns

TRUE on success, FALSE on error (err may be set)

See Also

IpatchXml