XML and libxml

XML and libxml —

Synopsis





                    GsfXMLIn;
                    GsfXMLInDoc;
gboolean            (*GsfXMLInUnknownFunc)              (GsfXMLIn *xin,
                                                         xmlChar const *elem,
                                                         xmlChar const **attrs);
                    GsfXMLInNS;
                    GsfXMLInNode;
void                (*GsfXMLInExtDtor)                  (GsfXMLIn *xin,
                                                         gpointer old_state);
enum                GsfXMLContent;
                    GsfXMLBlob;
#define             GSF_XML_IN_NODE_FULL                (parent_id, id, ns, name, has_content, 	
                                                         			     share_children_with_parent, check_ns, start, end, user)
#define             GSF_XML_IN_NODE                     (parent_id, id, ns, name, has_content, start, end)
#define             GSF_XML_IN_NODE_END
#define             GSF_XML_IN_NS                       (id, uri)
GsfXMLInDoc*        gsf_xml_in_doc_new                  (GsfXMLInNode const *nodes,
                                                         GsfXMLInNS const *ns);
void                gsf_xml_in_doc_free                 (GsfXMLInDoc *doc);
gboolean            gsf_xml_in_doc_parse                (GsfXMLInDoc *doc,
                                                         GsfInput *input,
                                                         gpointer user_state);
void                gsf_xml_in_doc_set_unknown_handler  (GsfXMLInDoc *doc,
                                                         GsfXMLInUnknownFunc handler);
void                gsf_xml_in_push_state               (GsfXMLIn *xin,
                                                         GsfXMLInDoc const *doc,
                                                         gpointer new_state,
                                                         GsfXMLInExtDtor dtor,
                                                         xmlChar const **attrs);
gboolean            gsf_xml_in_namecmp                  (GsfXMLIn const *xin,
                                                         char const *str,
                                                         unsigned int ns_id,
                                                         char const *name);
charconst  *        gsf_xml_in_check_ns                 (GsfXMLIn const *xin,
                                                         char const *str,
                                                         unsigned int ns_id);

                    GsfXMLOut;
GsfXMLOut*          gsf_xml_out_new                     (GsfOutput *output);
void                gsf_xml_out_set_doc_type            (GsfXMLOut *xml,
                                                         char const *type);
void                gsf_xml_out_start_element           (GsfXMLOut *xml,
                                                         char const *id);
charconst *         gsf_xml_out_end_element             (GsfXMLOut *xml);
void                gsf_xml_out_add_cstr                (GsfXMLOut *xml,
                                                         char const *id,
                                                         char const *val_utf8);
void                gsf_xml_out_add_cstr_unchecked      (GsfXMLOut *xml,
                                                         char const *id,
                                                         char const *val_utf8);
void                gsf_xml_out_add_bool                (GsfXMLOut *xml,
                                                         char const *id,
                                                         gboolean val);
void                gsf_xml_out_add_int                 (GsfXMLOut *xml,
                                                         char const *id,
                                                         int val);
void                gsf_xml_out_add_uint                (GsfXMLOut *xml,
                                                         char const *id,
                                                         unsigned int val);
void                gsf_xml_out_add_float               (GsfXMLOut *xml,
                                                         char const *id,
                                                         double val,
                                                         int precision);
void                gsf_xml_out_add_enum                (GsfXMLOut *xml,
                                                         char const *id,
                                                         GType etype,
                                                         gint val);
void                gsf_xml_out_add_color               (GsfXMLOut *xml,
                                                         char const *id,
                                                         unsigned int r,
                                                         unsigned int g,
                                                         unsigned int b);
void                gsf_xml_out_add_base64              (GsfXMLOut *xml,
                                                         char const *id,
                                                         guint8 const *data,
                                                         unsigned int len);
void                gsf_xml_out_simple_element          (GsfXMLOut *xml,
                                                         char const *id,
                                                         char const *content);
void                gsf_xml_out_simple_float_element    (GsfXMLOut *xml,
                                                         char const *id,
                                                         double val,
                                                         int precision);
void                gsf_xml_out_simple_int_element      (GsfXMLOut *xml,
                                                         char const *id,
                                                         int val);

xmlParserCtxt*      gsf_xml_parser_context              (GsfInput *input);
gboolean            gsf_xml_gvalue_from_str             (GValue *res,
                                                         GType t,
                                                         char const *str);
int                 gsf_xmlDocFormatDump                (GsfOutput *output,
                                                         xmlDoc *cur,
                                                         char const *encoding,
                                                         gboolean format);

Object Hierarchy


  GObject
   +----GsfXMLOut

Description

Details

GsfXMLIn

typedef struct {
	/* public state : read only */
	gpointer	    user_state;
	GString		   *content;
	GsfXMLInDoc  const *doc;
	GsfXMLInNode const *node;	/* current node (not on the stack) */
	GSList	 	   *node_stack;	/* stack of GsfXMLInNode */
} GsfXMLIn;

GsfXMLInDoc

typedef struct _GsfXMLInDoc GsfXMLInDoc;

GsfXMLInUnknownFunc ()

gboolean            (*GsfXMLInUnknownFunc)              (GsfXMLIn *xin,
                                                         xmlChar const *elem,
                                                         xmlChar const **attrs);

xin :
elem :
attrs :
Returns :

GsfXMLInNS

typedef struct {
	char const *uri;
	unsigned    ns_id;
} GsfXMLInNS;

GsfXMLInNode

typedef struct {
	char const *id;		/* unique in the entire tree */
	int	    ns_id;
	char const *name;
	char const *parent_id;
	void (*start) (GsfXMLIn *xin, xmlChar const **attrs);
	void (*end)   (GsfXMLIn *xin, GsfXMLBlob *unknown);

	union {
		int	    v_int;
		gboolean    v_bool;
		gpointer    v_blob;
		char const *v_str;
	} user_data;
	GsfXMLContent has_content;

	unsigned int check_children_for_ns : 1;
	unsigned int share_children_with_parent : 1;
} GsfXMLInNode;

GsfXMLInExtDtor ()

void                (*GsfXMLInExtDtor)                  (GsfXMLIn *xin,
                                                         gpointer old_state);

xin :
old_state :

enum GsfXMLContent

typedef enum {
	GSF_XML_NO_CONTENT = FALSE,
	GSF_XML_CONTENT,
	GSF_XML_SHARED_CONTENT
} GsfXMLContent;

GsfXMLBlob

typedef struct _GsfXMLBlob GsfXMLBlob;

GSF_XML_IN_NODE_FULL()

#define             GSF_XML_IN_NODE_FULL(parent_id, id, ns, name, has_content, 	\
            			     share_children_with_parent, check_ns, start, end, user)

parent_id :
id :
ns :
name :
has_content :
share_children_with_parent :
check_ns :
start :
end :
user :

GSF_XML_IN_NODE()

#define             GSF_XML_IN_NODE(parent_id, id, ns, name, has_content, start, end)

parent_id :
id :
ns :
name :
has_content :
start :
end :

GSF_XML_IN_NODE_END

#define             GSF_XML_IN_NODE_END

GSF_XML_IN_NS()

#define             GSF_XML_IN_NS(id, uri)

id :
uri :

gsf_xml_in_doc_new ()

GsfXMLInDoc*        gsf_xml_in_doc_new                  (GsfXMLInNode const *nodes,
                                                         GsfXMLInNS const *ns);

Combine the nodes in the NULL terminated array starting at nodes with the name spaces in the NULL terminated array starting at ns. Prepare the data structures necessary to validate a doument based on that description.

nodes : an array of node descriptors
ns : an array of namespace identifiers
Returns : NULL on error

gsf_xml_in_doc_free ()

void                gsf_xml_in_doc_free                 (GsfXMLInDoc *doc);

Free up resources

doc :

gsf_xml_in_doc_parse ()

gboolean            gsf_xml_in_doc_parse                (GsfXMLInDoc *doc,
                                                         GsfInput *input,
                                                         gpointer user_state);

Read an xml document from input and parse based on the the descriptor in doc

doc :
input :
user_state :
Returns : FALSE on error

gsf_xml_in_doc_set_unknown_handler ()

void                gsf_xml_in_doc_set_unknown_handler  (GsfXMLInDoc *doc,
                                                         GsfXMLInUnknownFunc handler);

Call the function handler when an unexpected child node is found

doc : GsfXMLInDoc
handler : The function to call

gsf_xml_in_push_state ()

void                gsf_xml_in_push_state               (GsfXMLIn *xin,
                                                         GsfXMLInDoc const *doc,
                                                         gpointer new_state,
                                                         GsfXMLInExtDtor dtor,
                                                         xmlChar const **attrs);

Take the first node from doc as the current node and call it's start handler.

xin : GsfXMLIn
doc : GsfXMLInDoc
new_state :
dtor : GsfXMLInExtDtor
attrs :

gsf_xml_in_namecmp ()

gboolean            gsf_xml_in_namecmp                  (GsfXMLIn const *xin,
                                                         char const *str,
                                                         unsigned int ns_id,
                                                         char const *name);

xin : The GsfXMLIn we are reading from.
str : The potentially namespace qualified node name.
ns_id : The name space id to check
name : The target node name
Returns : TRUE if str == ns_id:name according to state.

gsf_xml_in_check_ns ()

charconst  *        gsf_xml_in_check_ns                 (GsfXMLIn const *xin,
                                                         char const *str,
                                                         unsigned int ns_id);

According to state is str in the namespace ns_id ?

xin :
str :
ns_id :
Returns : a pointer to str after the namespace if successful, otherwise NULL.

GsfXMLOut

typedef struct _GsfXMLOut GsfXMLOut;

gsf_xml_out_new ()

GsfXMLOut*          gsf_xml_out_new                     (GsfOutput *output);

output :
Returns :

gsf_xml_out_set_doc_type ()

void                gsf_xml_out_set_doc_type            (GsfXMLOut *xml,
                                                         char const *type);

Store some optional some <!DOCTYPE .. > content

xml : GsfXMLOut
type :

gsf_xml_out_start_element ()

void                gsf_xml_out_start_element           (GsfXMLOut *xml,
                                                         char const *id);

xml :
id :

gsf_xml_out_end_element ()

charconst *         gsf_xml_out_end_element             (GsfXMLOut *xml);

xml :
Returns :

gsf_xml_out_add_cstr ()

void                gsf_xml_out_add_cstr                (GsfXMLOut *xml,
                                                         char const *id,
                                                         char const *val_utf8);

dump val_utf8 to an attribute named id or as the nodes content escaping characters as necessary. If val_utf8 is NULL do nothing (no warning, no output)

xml :
id : optionally NULL for content
val_utf8 : a utf8 encoded string

gsf_xml_out_add_cstr_unchecked ()

void                gsf_xml_out_add_cstr_unchecked      (GsfXMLOut *xml,
                                                         char const *id,
                                                         char const *val_utf8);

dump val_utf8 to an attribute named id without checking to see if the content needs escaping. A useful performance enhancement when the application knows that structure of the content well. If val_utf8 is NULL do nothing (no warning, no output)

xml :
id : optionally NULL for content
val_utf8 : a utf8 encoded string to export

gsf_xml_out_add_bool ()

void                gsf_xml_out_add_bool                (GsfXMLOut *xml,
                                                         char const *id,
                                                         gboolean val);

dump boolean value val to an attribute named id or as the nodes content Use '1' or '0' to simplify import

xml :
id : optionally NULL for content
val : a boolean

gsf_xml_out_add_int ()

void                gsf_xml_out_add_int                 (GsfXMLOut *xml,
                                                         char const *id,
                                                         int val);

dump integer value val to an attribute named id or as the nodes content

xml :
id : optionally NULL for content
val : the value

gsf_xml_out_add_uint ()

void                gsf_xml_out_add_uint                (GsfXMLOut *xml,
                                                         char const *id,
                                                         unsigned int val);

dump unsigned integer value val to an attribute named id or as the nodes content

xml :
id : optionally NULL for content
val : the value

gsf_xml_out_add_float ()

void                gsf_xml_out_add_float               (GsfXMLOut *xml,
                                                         char const *id,
                                                         double val,
                                                         int precision);

dump float value val to an attribute named id or as the nodes content with precision precision. The number will be formattted according to the "C" locale.

xml :
id : optionally NULL for content
val : the value
precision : the number of significant digits to use, -1 meaning "enough".

gsf_xml_out_add_enum ()

void                gsf_xml_out_add_enum                (GsfXMLOut *xml,
                                                         char const *id,
                                                         GType etype,
                                                         gint val);

xml :
id :
etype :
val :

gsf_xml_out_add_color ()

void                gsf_xml_out_add_color               (GsfXMLOut *xml,
                                                         char const *id,
                                                         unsigned int r,
                                                         unsigned int g,
                                                         unsigned int b);

dump Color r.g.b to an attribute named id or as the nodes content

xml :
id : optionally NULL for content
r :
g :
b :

gsf_xml_out_add_base64 ()

void                gsf_xml_out_add_base64              (GsfXMLOut *xml,
                                                         char const *id,
                                                         guint8 const *data,
                                                         unsigned int len);

dump len bytes in data into the content of node id using base64

xml :
id : optionally NULL for content
data :
len :

gsf_xml_out_simple_element ()

void                gsf_xml_out_simple_element          (GsfXMLOut *xml,
                                                         char const *id,
                                                         char const *content);

A convenience routine

xml :
id :
content :

gsf_xml_out_simple_float_element ()

void                gsf_xml_out_simple_float_element    (GsfXMLOut *xml,
                                                         char const *id,
                                                         double val,
                                                         int precision);

A convenience routine

xml :
id :
val :
precision :

gsf_xml_out_simple_int_element ()

void                gsf_xml_out_simple_int_element      (GsfXMLOut *xml,
                                                         char const *id,
                                                         int val);

A convenience routine

xml :
id :
val :

gsf_xml_parser_context ()

xmlParserCtxt*      gsf_xml_parser_context              (GsfInput *input);

Create a libxml2 pull style parser context wrapper around a gsf input. This signature will probably change to supply a SAX structure.

Note

This adds a reference to input.

Note

A simple wrapper around a cleaner implementation that will fold in when we add other api changes. Its not worth bumping just for this.

input :
Returns : : A parser context or NULL

gsf_xml_gvalue_from_str ()

gboolean            gsf_xml_gvalue_from_str             (GValue *res,
                                                         GType t,
                                                         char const *str);

res :
t :
str :
Returns :

gsf_xmlDocFormatDump ()

int                 gsf_xmlDocFormatDump                (GsfOutput *output,
                                                         xmlDoc *cur,
                                                         char const *encoding,
                                                         gboolean format);

output :
cur :
encoding :
format :
Returns :