XML and libxml

			GSF Reference Manual
Top \| Description \| Object Hierarchy \| Properties

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;
gboolean            (*GsfXMLProbeFunc)                  (const xmlChar *name,
                                                         const xmlChar *prefix,
                                                         const xmlChar *URI,
                                                         int nb_namespaces,
                                                         const xmlChar **namespaces,
                                                         int nb_attributes,
                                                         int nb_defaulted,
                                                         const xmlChar **attributes);
#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);
void                gsf_xml_in_doc_add_nodes            (GsfXMLInDoc *doc,
                                                         GsfXMLInNode const *nodes);
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);
char const  *       gsf_xml_in_check_ns                 (GsfXMLIn const *xin,
                                                         char const *str,
                                                         unsigned int ns_id);
GsfInput *          gsf_xml_in_get_input                (GsfXMLIn const *xin);
gboolean            gsf_xml_probe                       (GsfInput *input,
                                                         GsfXMLProbeFunc func);

                    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);
char const *        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
  "sink"                     GsfOutput*            : Read / Write / Construct Only

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) */
} GsfXMLIn;

gpointer `user_state`;	user data
GString *`content`;	the current node content
GsfXMLInDoc const *`doc`;	GsfXMLInDoc
GsfXMLInNode const *`node`;	current node (not on the stack)

GsfXMLInDoc

typedef struct _GsfXMLInDoc GsfXMLInDoc;

GsfXMLInUnknownFunc ()

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

GsfXMLInNS

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

char const *uri;

URI

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;

char const *`id`;	identifier unique in the entire tree
int `ns_id`;	namespace identifier
char const *`name`;	node name
char const *`parent_id`;	parent node identifier
`start` ()	callback for the node opening
`end` ()	callback for node end
GsfXMLContent `has_content`;	whether the node has content
unsigned int `check_children_for_ns` : 1;	whetehr to check namespace for children
unsigned int `share_children_with_parent` : 1;	whether to share children with parent.

GsfXMLInExtDtor ()

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

enum GsfXMLContent

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

Controls the handling of character data within a parser node.

`GSF_XML_NO_CONTENT`	node has no cstr contents
`GSF_XML_CONTENT`	node has cstr contents
`GSF_XML_SHARED_CONTENT`	node has contents that is shared with children

GsfXMLBlob

typedef struct _GsfXMLBlob GsfXMLBlob;

GsfInputHTTP

typedef struct _GsfInputHTTP GsfInputHTTP;

GsfXMLProbeFunc ()

gboolean            (*GsfXMLProbeFunc)                  (const xmlChar *name,
                                                         const xmlChar *prefix,
                                                         const xmlChar *URI,
                                                         int nb_namespaces,
                                                         const xmlChar **namespaces,
                                                         int nb_attributes,
                                                         int nb_defaulted,
                                                         const xmlChar **attributes);

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)

GSF_XML_IN_NODE()

#define             GSF_XML_IN_NODE(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)

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_add_nodes ()

void                gsf_xml_in_doc_add_nodes            (GsfXMLInDoc *doc,
                                                         GsfXMLInNode const *nodes);

Adds additional nodes to the structure of doc

`doc` :	GsfXMLInDoc
`nodes` :	`NULL` terminated array of GsfXMLInNode

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` :	GsfXMLInDoc
`input` :	GsfInput
`user_state` :	arbitrary content stored in the parser
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. [scope 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 its start handler.

`xin` :	GsfXMLIn
`doc` :	GsfXMLInDoc
`new_state` :	arbitrary content for the parser
`dtor` :	GsfXMLInExtDtor. [scope call]
`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);

Checks to see if str is the same as ns_id::name with either an explicit namespace or the current default namespace.

`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 ()

char const  *       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` :	string to check
`ns_id` :	the namespace id
Returns :	a pointer to `str` after the namespace if successful, otherwise `NULL`. [transfer none]

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. [transfer none]

gsf_xml_probe ()

gboolean            gsf_xml_probe                       (GsfInput *input,
                                                         GsfXMLProbeFunc func);

`input` :	GsfInput
`func` :	GsfXMLProbeFunc. [scope call]
Returns :	TRUE on success.

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);

Get the GsfInput we are parsing from.

`xout` :	GsfXMLOut
Returns :	GsfInput or `NULL`. [transfer none]

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 ()

char const *        gsf_xml_out_end_element             (GsfXMLOut *xout);

Closes/ends an XML element.

`xout` :	GsfXMLOut
Returns :	the element that has been closed. [transfer none]

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` :	tag id or `NULL` for content. [allow-none]
`val_utf8` :	a utf8 encoded string. [allow-none]

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` :	tag id or `NULL` for content. [allow-none]
`val_utf8` :	a utf8 encoded string to export. [allow-none]

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` :	tag id or `NULL` for content. [allow-none]
`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` :	tag id or `NULL` for content. [allow-none]
`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` :	tag id or `NULL` for content. [allow-none]
`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` :	tag id or `NULL` for content. [allow-none]
`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` :	tag id or `NULL` for content. [allow-none]
`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` :	tag id or `NULL` for content. [allow-none]
`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` :	tag id or `NULL` for content. [allow-none]
`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` :	tag id or `NULL` for content. [allow-none]
`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);

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.

NOTE: skipped since xmlParserCtxt is not exported to introspection.

`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);

Dumps the document cur into output.

`output` :	GsfOutput
`cur` :	xmlDocPtr
`encoding` :	The encoding to use. [allow-none]
`format` :	`TRUE` to reformat the output.
Returns :	status from xmlSaveFormatFileTo.

Property Details

The `"pretty-print"` property

  "pretty-print"             gboolean              : Read / Write

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

Default value: TRUE

The `"sink"` property

  "sink"                     GsfOutput*            : Read / Write / Construct Only

The destination for writes.

XML and libxml

Synopsis

Object Hierarchy

Properties

Description

Details

GsfXMLIn

GsfXMLInDoc

GsfXMLInUnknownFunc ()

GsfXMLInNS

GsfXMLInNode

GsfXMLInExtDtor ()

enum GsfXMLContent

GsfXMLBlob

GsfInputHTTP

GsfXMLProbeFunc ()

GSF_XML_IN_NODE_FULL()

GSF_XML_IN_NODE()

GSF_XML_IN_NODE_END

GSF_XML_IN_NS()

GSF_XML_IN_NS_END

gsf_xml_in_doc_new ()

gsf_xml_in_doc_free ()

gsf_xml_in_doc_add_nodes ()

gsf_xml_in_doc_parse ()

gsf_xml_in_doc_set_unknown_handler ()

gsf_xml_in_push_state ()

gsf_xml_in_namecmp ()

gsf_xml_in_check_ns ()

gsf_xml_in_get_input ()

gsf_xml_probe ()

GsfXMLOut

gsf_xml_out_new ()

gsf_xml_out_set_doc_type ()

gsf_xml_out_get_output ()

gsf_xml_out_start_element ()

gsf_xml_out_end_element ()

gsf_xml_out_add_cstr ()

gsf_xml_out_add_cstr_unchecked ()

gsf_xml_out_add_bool ()

gsf_xml_out_add_int ()

gsf_xml_out_add_uint ()

gsf_xml_out_add_float ()

gsf_xml_out_add_enum ()

gsf_xml_out_add_color ()

gsf_xml_out_add_base64 ()

gsf_xml_out_add_gvalue ()

gsf_xml_out_simple_element ()

gsf_xml_out_simple_float_element ()

gsf_xml_out_simple_int_element ()

gsf_input_http_get_content_type ()

gsf_input_http_get_type ()

gsf_input_http_get_url ()

gsf_xml_parser_context ()

Note

Note

gsf_xml_gvalue_from_str ()

gsf_xmlDocFormatDump ()

Property Details

The "pretty-print" property

The "sink" property

The `"pretty-print"` property

The `"sink"` property