XML and libxml

## 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;
    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.