XML and libxml: GSF Reference Manual

## XML and libxml XML and libxml |

## Functions

gboolean | (*GsfXMLInUnknownFunc) ()
void | (*GsfXMLInExtDtor) ()
gboolean | (*GsfXMLProbeFunc) ()
#define | GSF_XML_IN_NODE_FULL()
#define | GSF_XML_IN_NODE()
#define | GSF_XML_IN_NS()
GsfXMLInDoc * | gsf_xml_in_doc_new ()
void | gsf_xml_in_doc_free ()
void | gsf_xml_in_doc_add_nodes ()
gboolean | gsf_xml_in_doc_parse ()
void | gsf_xml_in_doc_set_unknown_handler ()
void | gsf_xml_in_push_state ()
gboolean | gsf_xml_in_namecmp ()
char const * | gsf_xml_in_check_ns ()
GsfInput * | gsf_xml_in_get_input ()
void | gsf_xml_in_set_silent_unknowns ()
gboolean | gsf_xml_probe ()
GsfXMLOut * | gsf_xml_out_new ()
void | gsf_xml_out_set_doc_type ()
GsfOutput * | gsf_xml_out_get_output ()
void | gsf_xml_out_start_element ()
char const * | gsf_xml_out_end_element ()
void | gsf_xml_out_add_cstr ()
void | gsf_xml_out_add_cstr_unchecked ()
void | gsf_xml_out_add_bool ()
void | gsf_xml_out_add_int ()
void | gsf_xml_out_add_uint ()
void | gsf_xml_out_add_float ()
void | gsf_xml_out_add_enum ()
void | gsf_xml_out_add_color ()
void | gsf_xml_out_add_base64 ()
void | gsf_xml_out_add_gvalue ()
void | gsf_xml_out_simple_element ()
void | gsf_xml_out_simple_float_element ()
void | gsf_xml_out_simple_int_element ()
gboolean | gsf_xml_out_get_pretty_print ()
gboolean | gsf_xml_out_set_pretty_print ()
gchar * | gsf_input_http_get_content_type ()
GType | gsf_input_http_get_type ()
gchar * | gsf_input_http_get_url ()
xmlParserCtxt * | gsf_xml_parser_context ()
gboolean | gsf_xml_gvalue_from_str ()
int | gsf_xmlDocFormatDump ()

## Properties

gboolean | pretty-print | Read / Write
GsfOutput * | sink | Read / Write / Construct Only

## Types and Values

| GsfXMLIn
| GsfXMLInDoc
| GsfXMLInNS
| GsfXMLInNode
enum | GsfXMLContent
| GsfXMLBlob
| GsfInputHTTP
#define | GSF_XML_IN_NODE_END
#define | GSF_XML_IN_NS_END
| GsfXMLOut

## Object Hierarchy

        GObject
        ├── GsfInput
        │   ╰── GsfInputHTTP
        ╰── GsfXMLOut

## Description

## Functions

### GsfXMLInUnknownFunc ()

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

### GsfXMLInExtDtor ()

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

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

    #define             GSF_XML_IN_NS(id, uri)

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

#### Parameters

nodes | an array of node descriptors. | [array zero-terminated=1]
ns | an array of namespace identifiers. | [array zero-terminated=1]

#### Returns

a GsfXMLInDoc.

[nullable]

### gsf_xml_in_doc_free ()

    void
    gsf_xml_in_doc_free (GsfXMLInDoc *doc);

Free up resources

#### Parameters

doc | A 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`

#### Parameters

doc | GsfXMLInDoc |
nodes | `NULL` terminated array of GsfXMLInNode. | [array zero-terminated=1]

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

#### Parameters

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

#### Parameters

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.

#### Parameters

xin | GsfXMLIn |
doc | GsfXMLInDoc |
new_state | arbitrary content for the parser |
dtor | GsfXMLInExtDtor. | [scope call]
attrs | array of xmlChar const *. | [array][element-type utf8]

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

#### Parameters

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

#### Parameters

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][nullable]

### gsf_xml_in_get_input ()

    GsfInput *
    gsf_xml_in_get_input (GsfXMLIn const *xin);

(New in 1.14.2)

#### Parameters

xin | GsfXMLIn |

#### Returns

(but does not reference) the stream being parsed.

[transfer none]

### gsf_xml_in_set_silent_unknowns ()

    void
    gsf_xml_in_set_silent_unknowns (GsfXMLIn *xin,
                                    gboolean silent);

(New in 1.14.33)

This provides a means to silently ignore unknown tags in contexts where they are expected.

#### Parameters

xin | GsfXMLIn |
silent | whether to be silent about unknown tags |

### gsf_xml_probe ()

    gboolean
    gsf_xml_probe (GsfInput *input,
                   GsfXMLProbeFunc func);

#### Parameters

input | GsfInput |
func | GsfXMLProbeFunc. | [scope call]

#### Returns

TRUE on success.

### gsf_xml_out_new ()

    GsfXMLOut *
    gsf_xml_out_new (GsfOutput *output);

Create an XML output stream.

#### Parameters

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 <!DOCTYPE .. > content

#### Parameters

xout | GsfXMLOut |
type | the document type declaration |

### gsf_xml_out_get_output ()

    GsfOutput *
    gsf_xml_out_get_output (GsfXMLOut const *xout);

Get the GsfOutput we are writing to..

#### Parameters

xout | GsfXMLOut |

#### Returns

GsfInput.

[transfer none][nullable]

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

#### Parameters

xout | GsfXMLOut |
id | Element name |

### gsf_xml_out_end_element ()

    char const *
    gsf_xml_out_end_element (GsfXMLOut *xout);

Closes/ends an XML element.

#### Parameters

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)

#### Parameters

xout | GsfXMLOut |
id | tag id, or `NULL` for node 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)

#### Parameters

xout | GsfXMLOut |
id | tag id, or `NULL` for node 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

#### Parameters

xout | GsfXMLOut |
id | tag id, or `NULL` for node 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

#### Parameters

xout | GsfXMLOut |
id | tag id, or `NULL` for node 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

#### Parameters

xout | GsfXMLOut |
id | tag id, or `NULL` for node 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.

#### Parameters

xout | GsfXMLOut |
id | tag id, or `NULL` for node 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` .

#### Parameters

xout | GsfXMLOut |
id | tag id, or `NULL` for node 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

#### Parameters

xout | GsfXMLOut |
id | tag id, or `NULL` for node 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

#### Parameters

xout | GsfXMLOut |
id | tag id, or `NULL` for node content. | [allow-none]
data | Data to be written. | [array length=len]
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.

#### Parameters

xout | GsfXMLOut |
id | tag id, or `NULL` for node 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` .

#### Parameters

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.

#### Parameters

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

#### Parameters

xout | GsfXMLOut |
id | Element name |
val | Element value |

### gsf_xml_out_get_pretty_print ()

    gboolean
    gsf_xml_out_get_pretty_print (GsfXMLOut *xout);

#### Parameters

xout | GsfXMLOut |

#### Returns

the current state of the pretty-print flag. Note, that gsf_xml_out_set_pretty_print will return the same value.

### gsf_xml_out_set_pretty_print ()

    gboolean
    gsf_xml_out_set_pretty_print (GsfXMLOut *xout,
                                  gboolean pp);

#### Parameters

xout | GsfXMLOut |
pp | new state of pretty-print flag. |

#### Returns

the previous state of the pretty-print flag.

### gsf_input_http_get_content_type ()

    gchar *
    gsf_input_http_get_content_type (GsfInputHTTP *input);

#### Parameters

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

#### Parameters

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.

This adds a reference to `input`.
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.

[skip]

#### Parameters

input | GsfInput |

#### Returns

A parser context.

[nullable]

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

#### Parameters

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

#### Parameters

output | GsfOutput |
cur | xmlDocPtr |
encoding | The encoding to use. | [allow-none]
format | `TRUE` to reformat the output. |

#### Returns

status from xmlSaveFormatFileTo.

## Types and Values

### GsfXMLIn

    typedef struct {
    	gpointer	    user_state;
    	GString		   *content;
    	GsfXMLInDoc  const *doc;
    	GsfXMLInNode const *node; /* current node (not on the stack) */
    } GsfXMLIn;

#### Members

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

### GsfXMLInDoc

    typedef struct _GsfXMLInDoc GsfXMLInDoc;

### GsfXMLInNS

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

#### Members

char const *`uri`; | URI |
unsigned int `ns_id`; |  |

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

#### Members

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; | whether to check namespace for children |
unsigned int `share_children_with_parent` : 1; | whether to share children with parent. |

### enum GsfXMLContent

Controls the handling of character data within a parser node.

#### Members

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 |
GSF_XML_2ND | node is second or later occurrence |

### GsfXMLBlob

    typedef struct _GsfXMLBlob GsfXMLBlob;

### GsfInputHTTP

    typedef struct _GsfInputHTTP GsfInputHTTP;

### GSF_XML_IN_NODE_END

    #define             GSF_XML_IN_NODE_END

### GSF_XML_IN_NS_END

    #define             GSF_XML_IN_NS_END

### GsfXMLOut

    typedef struct _GsfXMLOut GsfXMLOut;

## Property Details

### The `“pretty-print”` property

      “pretty-print”             gboolean

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

Owner: GsfXMLOut

Flags: Read / Write

Default value: TRUE

### The `“sink”` property

      “sink”                     GsfOutput *

The destination for writes.

Owner: GsfXMLOut

Flags: Read / Write / Construct Only