Top | ![]() |
![]() |
![]() |
![]() |
gboolean | (*IpatchXmlEncodeFunc) () |
gboolean | (*IpatchXmlDecodeFunc) () |
void | ipatch_xml_register_handler () |
void | ipatch_xml_register_handler_full () |
gboolean | ipatch_xml_lookup_handler () |
gboolean | ipatch_xml_lookup_handler_by_prop_name () |
gboolean | ipatch_xml_encode_object () |
gboolean | ipatch_xml_encode_property () |
gboolean | ipatch_xml_encode_property_by_name () |
gboolean | ipatch_xml_encode_value () |
gboolean | ipatch_xml_decode_object () |
gboolean | ipatch_xml_decode_property () |
gboolean | ipatch_xml_decode_property_by_name () |
gboolean | ipatch_xml_decode_value () |
gboolean | ipatch_xml_default_encode_object_func () |
gboolean | ipatch_xml_default_encode_property_func () |
gboolean | ipatch_xml_default_encode_value_func () |
gboolean | ipatch_xml_default_decode_object_func () |
gboolean | ipatch_xml_default_decode_property_func () |
gboolean | ipatch_xml_default_decode_value_func () |
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).
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.
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, |
|
pspec |
Spec of property being decoded (property decoders only, |
|
value |
Value to decode to (property and GValue decoders only, |
|
err |
Location to store error value (or |
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]
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 |
|
encode_func |
Function to handle encoding (object/property/value -> XML) |
|
decode_func |
Function to handle decoding (XML -> object/property/value) |
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]
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 |
[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 |
[nullable] |
Since: 1.1.0
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]
type |
GObject or GValue type of handler to lookup |
|
pspec |
GObject property spec (or |
[nullable] |
encode_func |
Location to store encoding function (or |
[out][optional] |
decode_func |
Location to store decoding function (or |
[out][optional] |
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]
type |
GObject or GValue type of handler to lookup |
|
prop_name |
GObject property name (or |
[nullable] |
encode_func |
Location to store encoding function (or |
[out][optional] |
decode_func |
Location to store decoding function (or |
[out][optional] |
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.
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.
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.
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.
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.
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.
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.
gboolean ipatch_xml_decode_value (GNode *node
,GValue *value
,GError **err
);
Decodes a GValue from an XML node text value.
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]
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]
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]
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]
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]
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]