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;
                    GsfInputHTTP;
#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)
#define             GSF_XML_IN_NS_END
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);
GsfInput*           gsf_xml_in_get_input                (GsfXMLIn const *xin);

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

gchar*              gsf_input_http_get_content_type     (GsfInputHTTP *input);
GType               gsf_input_http_get_type             (void);
gchar*              gsf_input_http_get_url              (GsfInputHTTP *input);

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

Properties


  "pretty-print"             gboolean              : Read / Write

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;

GsfInputHTTP

typedef struct _GsfInputHTTP GsfInputHTTP;

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_NS_END

#define             GSF_XML_IN_NS_END

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 :

 GsfXMLInDoc

gsf_xml_in_doc_parse ()

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

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

doc :

 GsfXMLInDoc

input :

 GsfInput

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 :

 array of xmlChar const *

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 :

 GsfXMLIn

str :

ns_id :

Returns :

 a pointer to str after the namespace if successful, otherwise NULL.

gsf_xml_in_get_input ()

GsfInput*           gsf_xml_in_get_input                (GsfXMLIn const *xin);

(New in 1.14.2)

xin :

 GsfXMLIn

Returns :

 (but does not reference) the stream being parsed.

GsfXMLOut

typedef struct _GsfXMLOut GsfXMLOut;

gsf_xml_out_new ()

GsfXMLOut*          gsf_xml_out_new                     (GsfOutput *output);

Create an XML output stream.

output :

 GsfOutput

Returns :

 GsfXMLOut

gsf_xml_out_set_doc_type ()

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

Store some optional some <!DOCTYPE .. > content

xout :

 GsfXMLOut

type :

 the document type declaration

gsf_xml_out_get_output ()

GsfOutput*          gsf_xml_out_get_output              (GsfXMLOut const *xout);

xout :

Returns :

gsf_xml_out_start_element ()

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

Output a start element id, if necessary preceeded by an XML declaration.

xout :

 GsfXMLOut

id :

 Element name

gsf_xml_out_end_element ()

charconst *         gsf_xml_out_end_element             (GsfXMLOut *xout);

Closes/ends an XML element.

xout :

 GsfXMLOut

Returns :

 the element that has been closed.

gsf_xml_out_add_cstr ()

void                gsf_xml_out_add_cstr                (GsfXMLOut *xout,
                                                         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)

xout :

 GsfXMLOut

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 *xout,
                                                         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)

xout :

 GsfXMLOut

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 *xout,
                                                         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

xout :

 GsfXMLOut

id :

 optionally NULL for content

val :

 a boolean

gsf_xml_out_add_int ()

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

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

xout :

 GsfXMLOut

id :

 optionally NULL for content

val :

 the value

gsf_xml_out_add_uint ()

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

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

xout :

 GsfXMLOut

id :

 optionally NULL for content

val :

 the value

gsf_xml_out_add_float ()

void                gsf_xml_out_add_float               (GsfXMLOut *xout,
                                                         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.

xout :

 GsfXMLOut

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 *xout,
                                                         char const *id,
                                                         GType etype,
                                                         gint val);

Output the name of value val of enumeration type etype.

xout :

 GsfXMLOut

id :

 optionally NULL for content

etype :

 GType

val :

 enum element number

gsf_xml_out_add_color ()

void                gsf_xml_out_add_color               (GsfXMLOut *xout,
                                                         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

xout :

 GsfXMLOut

id :

 optionally NULL for content

r :

 Red value

g :

 Green value

b :

 Blue value

gsf_xml_out_add_base64 ()

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

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

xout :

 GsfXMLOut

id :

 optionally NULL for content

data :

 Data to be written

len :

 Length of data

gsf_xml_out_add_gvalue ()

void                gsf_xml_out_add_gvalue              (GsfXMLOut *xout,
                                                         char const *id,
                                                         GValue const *val);

Output the value of val as a string. Does NOT store any type information with the string, just thevalue.

xout :

 GsfXMLOut

id :

 optionally NULL for content

val :

 GValue

gsf_xml_out_simple_element ()

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

Convenience routine to output a simple id element with content content.

xout :

 GsfXMLOut

id :

 Element name

content :

 Content of the element

gsf_xml_out_simple_float_element ()

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

Convenience routine to output an element id with float value val using precision significant digits.

xout :

 GsfXMLOut

id :

 Element name

val :

 Element value

precision :

 the number of significant digits to use, -1 meaning "enough".

gsf_xml_out_simple_int_element ()

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

Convenience routine to output an element id with integer value val.

xout :

 GsfXMLOut

id :

 Element name

val :

 Element value

gsf_input_http_get_content_type ()

gchar*              gsf_input_http_get_content_type     (GsfInputHTTP *input);

input :

 GsfInputHTTP

Returns :

 an allocated string containing the Content-Type field of the HTTP response.

gsf_input_http_get_type ()

GType               gsf_input_http_get_type             (void);

Returns :

gsf_input_http_get_url ()

gchar*              gsf_input_http_get_url              (GsfInputHTTP *input);

input :

 GsfInputHTTP

Returns :

 an allocated string containing the URL used for input.

gsf_xml_parser_context ()

xmlParserCtxt*      gsf_xml_parser_context              (GsfInput *input);

Create a libxml2 pull style parser context wrapper around gsf input 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 :

 GsfInput

Returns :

 A parser context or NULL

gsf_xml_gvalue_from_str ()

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

Try to parse str as a value of type t into res.

res :

 Result value

t :

 Type of data

str :

 Value string

Returns :

 True when parsing of str as a value of type t was succesfull; false otherwise.

gsf_xmlDocFormatDump ()

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

output :

cur :

encoding :

format :

Returns :

Property Details

The "pretty-print" property

  "pretty-print"             gboolean              : Read / Write

Should the output auto-indent elements to make reading easier.

Default value: TRUE