XML and libxml

## XML and libxml 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;
    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);
    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);
    const char* 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_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 allocated by gsf_xml_in_doc_prep

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

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

    const char* 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`.

`xml` : |
`id` : | optionally NULL for content
`val` : | the value
`precision` : | the number of decimal points to display

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