IpatchXmlObject

IpatchXmlObject — GObject related XML tree functions

Stability Level

Stable, unless otherwise indicated

Synopsis

gboolean            (*IpatchXmlEncodeFunc)              (GNode *node,
                                                         GObject *object,
                                                         GParamSpec *pspec,
                                                         GValue *value,
                                                         GError **err);
gboolean            (*IpatchXmlDecodeFunc)              (GNode *node,
                                                         GObject *object,
                                                         GParamSpec *pspec,
                                                         GValue *value,
                                                         GError **err);
void                ipatch_xml_register_handler         (GType type,
                                                         const char *prop_name,
                                                         IpatchXmlEncodeFunc encode_func,
                                                         IpatchXmlDecodeFunc decode_func);
gboolean            ipatch_xml_lookup_handler           (GType type,
                                                         GParamSpec *pspec,
                                                         IpatchXmlEncodeFunc *encode_func,
                                                         IpatchXmlDecodeFunc *decode_func);
gboolean            ipatch_xml_lookup_handler_by_prop_name
                                                        (GType type,
                                                         const char *prop_name,
                                                         IpatchXmlEncodeFunc *encode_func,
                                                         IpatchXmlDecodeFunc *decode_func);
gboolean            ipatch_xml_encode_object            (GNode *node,
                                                         GObject *object,
                                                         gboolean create_element,
                                                         GError **err);
gboolean            ipatch_xml_encode_property          (GNode *node,
                                                         GObject *object,
                                                         GParamSpec *pspec,
                                                         gboolean create_element,
                                                         GError **err);
gboolean            ipatch_xml_encode_property_by_name  (GNode *node,
                                                         GObject *object,
                                                         const char *propname,
                                                         gboolean create_element,
                                                         GError **err);
gboolean            ipatch_xml_encode_value             (GNode *node,
                                                         GValue *value,
                                                         GError **err);
gboolean            ipatch_xml_decode_object            (GNode *node,
                                                         GObject *object,
                                                         GError **err);
gboolean            ipatch_xml_decode_property          (GNode *node,
                                                         GObject *object,
                                                         GParamSpec *pspec,
                                                         GError **err);
gboolean            ipatch_xml_decode_property_by_name  (GNode *node,
                                                         GObject *object,
                                                         const char *propname,
                                                         GError **err);
gboolean            ipatch_xml_decode_value             (GNode *node,
                                                         GValue *value,
                                                         GError **err);
gboolean            ipatch_xml_default_encode_object_func
                                                        (GNode *node,
                                                         GObject *object,
                                                         GParamSpec *pspec,
                                                         GValue *value,
                                                         GError **err);
gboolean            ipatch_xml_default_encode_property_func
                                                        (GNode *node,
                                                         GObject *object,
                                                         GParamSpec *pspec,
                                                         GValue *value,
                                                         GError **err);
gboolean            ipatch_xml_default_encode_value_func
                                                        (GNode *node,
                                                         GObject *object,
                                                         GParamSpec *pspec,
                                                         GValue *value,
                                                         GError **err);
gboolean            ipatch_xml_default_decode_object_func
                                                        (GNode *node,
                                                         GObject *object,
                                                         GParamSpec *pspec,
                                                         GValue *value,
                                                         GError **err);
gboolean            ipatch_xml_default_decode_property_func
                                                        (GNode *node,
                                                         GObject *object,
                                                         GParamSpec *pspec,
                                                         GValue *value,
                                                         GError **err);
gboolean            ipatch_xml_default_decode_value_func
                                                        (GNode *node,
                                                         GObject *object,
                                                         GParamSpec *pspec,
                                                         GValue *value,
                                                         GError **err);

Description

Functions for saving/loading GObject, GValue and GObject properties to/from XML trees. Includes a system for registering custom encoding and decoding handlers for objects, properties and value types.

Details

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.

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.

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.

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_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.

type :

 GObject or GValue type of handler to lookup

pspec :

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

encode_func :

 Location to store encoding function (or NULL)

decode_func :

 Location to store decoding function (or NULL)

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.

type :

 GObject or GValue type of handler to lookup

prop_name :

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

encode_func :

 Location to store encoding function (or NULL)

decode_func :

 Location to store decoding function (or NULL)

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.

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 to an XML node.

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.

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.

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. The default GObject decoder will only decode those properties which don't have the IPATCH_PARAM_NO_SAVE flag set.

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. Note that the property is NOT checked for the IPATCH_PARAM_NO_SAVE flag.

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. Note that the property is NOT checked for the IPATCH_PARAM_NO_SAVE flag.

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.

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 for custom handlers to chain to the default if needed.

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.

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 for custom handlers to chain to the default if needed.

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.

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 for custom handlers to chain to the default if needed.

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 GValue decode handler. Useful for custom handlers to chain to the default if needed.

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
Generated by GTK-Doc V1.15