diff options
Diffstat (limited to 'docs/manual/xml.sgml')
| -rw-r--r-- | docs/manual/xml.sgml | 150 |
1 files changed, 132 insertions, 18 deletions
diff --git a/docs/manual/xml.sgml b/docs/manual/xml.sgml index 399a90739a..7cc518205c 100644 --- a/docs/manual/xml.sgml +++ b/docs/manual/xml.sgml @@ -38,7 +38,7 @@ main (int argc, char *argv[]) gst_init (&argc,&argv); if (argc != 2) { - g_print ("usage: %s <filename>\n", argv[0]); + g_print ("usage: %s <filename>\n", argv[0]); exit (-1); } @@ -120,7 +120,9 @@ main (int argc, char *argv[]) <sect1 id="sec-xml-load"> <title>Loading a GstElement from an XML file</title> <para> - A saved XML file can be loade with the gst_xml_new (filename, rootelement). + Before an XML file can be loaded, you must create a GstXML object. + A saved XML file can then be loaded with the + gst_xml_parse_file (xml, filename, rootelement) method. The root element can optionally left NULL. The following code example loads the previously created XML file and runs it. </para> @@ -128,37 +130,28 @@ main (int argc, char *argv[]) #include <stdlib.h> #include <gst/gst.h> -gboolean playing; - -/* eos will be called when the src element has an end of stream */ -void -eos (GstElement *element, gpointer data) -{ - g_print ("have eos, quitting\n"); - - playing = FALSE; -} - int main(int argc, char *argv[]) { GstXML *xml; GstElement *bin; - GstElement *disk; + gboolean ret; gst_init (&argc, &argv); - xml = gst_xml_new ("xmlTest.gst", NULL); + xml = gst_xml_new (); + + ret = gst_xml_parse_file(xml, "xmlTest.gst", NULL); + g_assert (ret == TRUE); bin = gst_xml_get_element (xml, "bin"); + g_assert (bin != NULL); gst_element_set_state (bin, GST_STATE_PLAYING); playing = TRUE; - while (playing) { - gst_bin_iterate (GST_BIN (bin)); - } + while (gst_bin_iterate(GST_BIN(bin))); gst_element_set_state (bin, GST_STATE_NULL); @@ -173,6 +166,127 @@ main(int argc, char *argv[]) gst_xml_get_topelements (xml) can be used to get a list of all toplevel elements in the XML file. </para> + <para> + In addition to loading a file, you can also load a from a xmlDocPtr and + an in memory buffer using gst_xml_parse_doc and gst_xml_parse_memory + respectivily. both of these methods return a gboolean indicating success + or failure of the requested action. + </para> + </sect1> + <sect1 id="sec-xml-custom"> + <title>Adding custom XML tags into the core XML data</title> + + <para> + It is possible to add custom XML tags to the core XML created with + gst_xml_write. This feature can be used by an application to add more + information to the save plugins. the editor will for example insert + the position of the elements on the screen using the custom XML tags. + </para> + <para> + It is strongly suggested to save and load the custom XML tags using + a namespace. This will solve the problem of having your XML tags + interfere with the core XML tags. + </para> + <para> + To insert a hook into the element saving procedure you can connect + a signal to the GstElement using the following piece of code: + </para> + <programlisting> +xmlNsPtr ns; + + ... + ns = xmlNewNs (NULL, "http://gstreamer.net/gst-test/1.0/", "test"); + ... + thread = gst_elementfactory_make("thread", "thread"); + gtk_signal_connect (GTK_OBJECT (thread), "object_saved", object_saved, g_strdup ("decoder thread")); + ... + </programlisting> + <para> + When the thread is saved, the object_save method will be caled. Our example + will insert a comment tag: + </para> + <programlisting> +static void +object_saved (GstObject *object, xmlNodePtr parent, gpointer data) +{ + xmlNodePtr child; + + child = xmlNewChild(parent, ns, "comment", NULL); + xmlNewChild(child, ns, "text", (gchar *)data); +} + </programlisting> + <para> + Adding the custom tag code to the above example you will get an XML file + with the custom tags in it. Here's an excerpt: + </para> + <programlisting> + ... + <gst:element> + <gst:name>thread</gst:name> + <gst:type>thread</gst:type> + <gst:version>0.1.0</gst:version> + ... + </gst:children> + <test:comment> + <test:text>decoder thread</test:text> + </test:comment> + </gst:element> + ... + </programlisting> + <para> + To retrieve the custom XML again, you need to attach a signal to + the GstXML object used to load the XML data. You can then parse your + custom XML from the XML tree whenever an object is loaded. + </para> + + <para> + We can extend our previous example with the following piece of + code. + </para> + + <programlisting> + xml = gst_xml_new (); + + gtk_signal_connect (GTK_OBJECT (xml), "object_loaded", xml_loaded, xml); + + ret = gst_xml_parse_file(xml, "xmlTest.gst", NULL); + g_assert (ret == TRUE); + </programlisting> + + <para> + Whenever a new object has been loaded, the xml_loaded function will be + called. this function looks like: + </para> + <programlisting> +static void +xml_loaded (GstXML *xml, GstObject *object, xmlNodePtr self, gpointer data) +{ + xmlNodePtr children = self->xmlChildrenNode; + + while (children) { + if (!strcmp (children->name, "comment")) { + xmlNodePtr nodes = children->xmlChildrenNode; + + while (nodes) { + if (!strcmp (nodes->name, "text")) { + gchar *name = g_strdup (xmlNodeGetContent (nodes)); + g_print ("object %s loaded with comment '%s'\n", + gst_object_get_name (object), name); + } + nodes = nodes->next; + } + } + children = children->next; + } +} + </programlisting> + <para> + As you can see, you'll get a handle to the GstXML object, the + newly loaded GstObject and the xmlNodePtr that was used to create + this object. In the above example we look for our special tag inside + the XML tree that was used to load the object and we print our + comment to the console. + </para> </sect1> </chapter> |