## 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