XML and libxml
3
GSF Library

# XML and libxml

## Synopsis

    #define     GSF_XML_IN_NS                   (id, uri)
    enum        GsfXMLContent;
                GsfXMLIn;
    int         gsf_xmlDocFormatDump            (GsfOutput *output,
                                                 xmlDoc *cur,
                                                 char const *encoding,
                                                 gboolean format);
    void        gsf_xml_in_doc_free             (GsfXMLInDoc *doc);
                GsfXMLBlob;
                GsfXMLOut;
                GsfXMLInDoc;
                GsfXMLInNS;
    #define     GSF_XML_IN_NODE_FULL            (parent_id, id, ns, name, has_content, 	\
    			     deprecated_unused_allow_unknown, check_ns, start, end, user)
    #define     GSF_XML_IN_NODE                 (parent_id, id, ns, name, has_content, start, end)
                GsfXMLInNode;
    gboolean    (*GsfXMLInUnknownFunc)          (GsfXMLIn *state,
                                                 xmlChar const *elem,
                                                 xmlChar const **attrs);
    xmlParserCtxt* gsf_xml_parser_context       (GsfInput *input);
    GsfXMLInDoc* gsf_xml_in_doc_new             (GsfXMLInNode *root,
                                                 GsfXMLInNS *ns);
    gboolean    gsf_xml_in_namecmp              (GsfXMLIn const *state,
                                                 char const *str,
                                                 unsigned int ns_id,
                                                 char const *name);
    gboolean    gsf_xml_in_parse                (GsfXMLIn *state,
                                                 GsfInput *input);
    charconst * gsf_xml_in_check_ns             (GsfXMLIn const *state,
                                                 char const *str,
                                                 unsigned int ns_id);
    void        gsf_xml_in_doc_extend           (GsfXMLInDoc *doc,
                                                 GsfXMLInNode *nodes);
    void        gsf_xml_in_doc_set_unknown_handler
                                                (GsfXMLInDoc *doc,
                                                 GsfXMLInUnknownFunc handler);
    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);

## Object Hierarchy

      GObject
       +----GsfXMLOut

## Description

## Details

### GSF_XML_IN_NS()

    #define     GSF_XML_IN_NS(id, uri)

`id` :

`uri` :

### enum GsfXMLContent

    typedef enum {
    	GSF_XML_NO_CONTENT,
    	GSF_XML_CONTENT,
    	GSF_XML_SHARED_CONTENT
    } GsfXMLContent;

### GsfXMLIn

    typedef struct {
    	GsfXMLInDoc  const *doc;	/* init before parsing */

        /* look but do not change */
    	GsfXMLInNode const *node;	/* current node */
    	GSList	 	   *state_stack;

    	GsfXMLInNS   const *default_ns;	/* optionally NULL */
    	GSList	 	   *ns_stack;

    	GString		*content;
    	gint		 unknown_depth;	/* handle recursive unknown tags */
    	GHashTable	*ns_prefixes;	/* current ns prefixes */
    	GPtrArray	*ns_by_id;		/* indexed by id */
    } GsfXMLIn;

### gsf_xmlDocFormatDump ()

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

`output` :

`cur` :

`encoding` :

`format` :

Returns :

### gsf_xml_in_doc_free ()

    void        gsf_xml_in_doc_free             (GsfXMLInDoc *doc);

Free up resources

`doc` :

### GsfXMLBlob

    typedef struct _GsfXMLBlob GsfXMLBlob;

### GsfXMLOut

    typedef struct _GsfXMLOut GsfXMLOut;

### GsfXMLInDoc

    typedef struct _GsfXMLInDoc GsfXMLInDoc;

### GsfXMLInNS

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

### GSF_XML_IN_NODE_FULL()

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

`parent_id` :

`id` :

`ns` :

`name` :

`has_content` :

  @\ allow_unknown: @\ allow_unknown: @\ allow_unknown: @\ allow_unknown: @\ allow_unknown: @\ allow_unknown: @\ allow_unknown: @\ allow_unknown: @\ allow_unknown: @\ allow_unknown: @\ allow_unknown: @\ allow_unknown: @\ allow_unknown: @\ allow_unknown: @\ allow_unknown: @\ allow_unknown: @\ allow_unknown: @\ allow_unknown: @\ allow_unknown: @\ allow_unknown: @\ allow_unknown: @\ allow_unknown: @\ allow_unknown: @\ allow_unknown: @\ allow_unknown: @\ allow_unknown: @\ allow_unknown: @\ allow_unknown: @\ allow_unknown: @\ allow_unknown: @\ allow_unknown: @\ allow_unknown: @\ allow_unknown: @\ allow_unknown: @\ allow_unknown: @\ allow_unknown: @\ deprecated_unused_allow_unknown: @\ deprecated_unused_allow_unknown: @\ deprecated_unused_allow_unknown: @\ deprecated_unused_allow_unknown: @\ deprecated_unused_allow_unknown: @\ deprecated_unused_allow_unknown: @\ deprecated_unused_allow_unknown: @\ deprecated_unused_allow_unknown: @\ deprecated_unused_allow_unknown: @\ deprecated_unused_allow_unknown: @\ deprecated_unused_allow_unknown: @\ deprecated_unused_allow_unknown: @\ deprecated_unused_allow_unknown: @\ deprecated_unused_allow_unknown: @\ deprecated_unused_allow_unknown: @\ deprecated_unused_allow_unknown: @\ deprecated_unused_allow_unknown: @\ deprecated_unused_allow_unknown: @\ deprecated_unused_allow_unknown: @\ deprecated_unused_allow_unknown: @\ deprecated_unused_allow_unknown: @\ deprecated_unused_allow_unknown: @\ deprecated_unused_allow_unknown: @\ deprecated_unused_allow_unknown: @\ deprecated_unused_allow_unknown: @\ deprecated_unused_allow_unknown: @\ deprecated_unused_allow_unknown: @\ deprecated_unused_allow_unknown: @\ deprecated_unused_allow_unknown: @\ deprecated_unused_allow_unknown: @\ deprecated_unused_allow_unknown: @\ deprecated_unused_allow_unknown: @\ deprecated_unused_allow_unknown: @\ deprecated_unused_allow_unknown: @\ deprecated_unused_allow_unknown: @\ deprecated_unused_allow_unknown: @\ deprecated_unused_allow_unknown: @\ deprecated_unused_allow_unknown: @\ deprecated_unused_allow_unknown: @\ deprecated_unused_allow_unknown: @\ deprecated_unused_allow_unknown: @\ deprecated_unused_allow_unknown: @\ deprecated_unused_allow_unknown: @\ deprecated_unused_allow_unknown: @\ deprecated_unused_allow_unknown: @\ deprecated_unused_allow_unknown: @\ deprecated_unused_allow_unknown: @\ deprecated_unused_allow_unknown: @\ deprecated_unused_allow_unknown: @\ deprecated_unused_allow_unknown: @\ deprecated_unused_allow_unknown: @\ deprecated_unused_allow_unknown: @\ deprecated_unused_allow_unknown: @\ deprecated_unused_allow_unknown: @\ deprecated_unused_allow_unknown: @\ deprecated_unused_allow_unknown: @\ deprecated_unused_allow_unknown: @\ deprecated_unused_allow_unknown: @\ deprecated_unused_allow_unknown: @\ deprecated_unused_allow_unknown: @\ deprecated_unused_allow_unknown: @\ deprecated_unused_allow_unknown: @\ deprecated_unused_allow_unknown: @\ deprecated_unused_allow_unknown: @\ deprecated_unused_allow_unknown: @\ deprecated_unused_allow_unknown: @\ deprecated_unused_allow_unknown: @\ deprecated_unused_allow_unknown: @\ deprecated_unused_allow_unknown: @\ deprecated_unused_allow_unknown: @\ deprecated_unused_allow_unknown: @\ deprecated_unused_allow_unknown: @\ deprecated_unused_allow_unknown: @\ deprecated_unused_allow_unknown: @\ deprecated_unused_allow_unknown: @\ deprecated_unused_allow_unknown: @\ deprecated_unused_allow_unknown: @\ deprecated_unused_allow_unknown: @\ deprecated_unused_allow_unknown: @\ deprecated_unused_allow_unknown: @\ deprecated_unused_allow_unknown: @\ deprecated_unused_allow_unknown: @\ deprecated_unused_allow_unknown: @\ deprecated_unused_allow_unknown: @\ deprecated_unused_allow_unknown: @\ deprecated_unused_allow_unknown: @\ deprecated_unused_allow_unknown: @\ deprecated_unused_allow_unknown: @\ deprecated_unused_allow_unknown: @\ deprecated_unused_allow_unknown: @\ deprecated_unused_allow_unknown: @\ deprecated_unused_allow_unknown: @\ deprecated_unused_allow_unknown: @\ deprecated_unused_allow_unknown: @\ deprecated_unused_allow_unknown: @\ deprecated_unused_allow_unknown: @\ deprecated_unused_allow_unknown: @\ deprecated_unused_allow_unknown: @\ deprecated_unused_allow_unknown:

`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` :

### GsfXMLInNode

    typedef struct {
    	char const *id;
    	int	    ns_id;
    	char const *name;
    	char const *parent_id;
    	gboolean parent_initialized;
    	GSList *groups;

    	unsigned	has_content;
    	gboolean	deprecated_unused_allow_unknown; /* remains here for binary compat */
    	gboolean	check_children_for_ns;

    	void (*start) (GsfXMLIn *state, xmlChar const **attrs);
    	void (*end)   (GsfXMLIn *state, GsfXMLBlob *unknown);

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

### GsfXMLInUnknownFunc ()

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

`state` :

`elem` :

`attrs` :

Returns :

### 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 : 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_in_doc_new ()

    GsfXMLInDoc* gsf_xml_in_doc_new             (GsfXMLInNode *root,
                                                 GsfXMLInNS *ns);

Put the nodes in the NULL terminated array starting at `root` and the name spaces in the NULL terminated array starting at `ns` together. Link them up and prepare the static data structures necessary to validate a doument based on that description.

`root` :

  an array of node descriptors

`ns` :

  an array of namespace identifiers

Returns :

  NULL on error

### gsf_xml_in_namecmp ()

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

`state` :

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

    gboolean    gsf_xml_in_parse                (GsfXMLIn *state,
                                                 GsfInput *input);

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

`state` :

`input` :

Returns :

  FALSE on error

### gsf_xml_in_check_ns ()

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

According to `state` is `str` in the namespace `ns_id` ?

`state` :

`str` :

`ns_id` :

Returns :

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

### gsf_xml_in_doc_extend ()

    void        gsf_xml_in_doc_extend           (GsfXMLInDoc *doc,
                                                 GsfXMLInNode *nodes);

`doc` :

`nodes` :

### 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_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` :