gst/gstxml.c

   1 /* GStreamer
   2  * Copyright (C) 1999,2000 Erik Walthinsen <omega@cse.ogi.edu>
   3  *                    2000 Wim Taymans <wtay@chello.be>
   4  *
   5  * gstxml.c: XML save/restore of pipelines
   6  *
   7  * This library is free software; you can redistribute it and/or
   8  * modify it under the terms of the GNU Library General Public
   9  * License as published by the Free Software Foundation; either
  10  * version 2 of the License, or (at your option) any later version.
  11  *
  12  * This library is distributed in the hope that it will be useful,
  13  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  14  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  15  * Library General Public License for more details.
  16  *
  17  * You should have received a copy of the GNU Library General Public
  18  * License along with this library; if not, write to the
  19  * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
  20  * Boston, MA 02111-1307, USA.
  21  */
  22
  23 /**
  24  * SECTION:gstxml
  25  * @short_description: XML save/restore operations of pipelines
  26  *
  27  * GStreamer pipelines can be saved to xml files using gst_xml_write_file().
  28  * They can be loaded back using gst_xml_parse_doc() / gst_xml_parse_file() /
  29  * gst_xml_parse_memory().
  30  * Additionally one can load saved pipelines into the gst-editor to inspect the
  31  * graph.
  32  *
  33  * #GstElement implementations need to override the #GstObjectClass.save_thyself()
  34  * and #GstObjectClass.restore_thyself() virtual functions of #GstObject.
  35  *
  36  * Deprecated: This feature is deprecated pipeline serialization to XML is
  37  * broken for all but the most simple pipelines. It will most likely be
  38  * removed in future. Don't use it.
  39  */
  40
  41 #include "gst_private.h"
  42
  43 #include "gstxml.h"
  44 #include "gstmarshal.h"
  45 #include "gstinfo.h"
  46 #include "gstbin.h"
  47
  48 #ifdef GST_DISABLE_DEPRECATED
  49 #if !defined(GST_DISABLE_LOADSAVE) && !defined(GST_REMOVE_DEPRECATED)
  50 #include <libxml/parser.h>
  51 xmlNodePtr gst_object_save_thyself (const GstObject * object,
  52     xmlNodePtr parent);
  53 GstObject *gst_object_load_thyself (xmlNodePtr parent);
  54 void gst_object_restore_thyself (GstObject * object, GstXmlNodePtr self);
  55
  56 #define GST_TYPE_XML            (gst_xml_get_type ())
  57 #define GST_XML(obj)            (G_TYPE_CHECK_INSTANCE_CAST ((obj), GST_TYPE_XML, GstXML))
  58 #define GST_IS_XML(obj)         (G_TYPE_CHECK_INSTANCE_TYPE ((obj), GST_TYPE_XML))
  59 #define GST_XML_CLASS(klass)    (G_TYPE_CHECK_CLASS_CAST ((klass), GST_TYPE_XML, GstXMLClass))
  60 #define GST_IS_XML_CLASS(klass) (G_TYPE_CHECK_CLASS_TYPE ((klass), GST_TYPE_XML))
  61 #define GST_XML_GET_CLASS(obj)  (G_TYPE_INSTANCE_GET_CLASS ((obj), GST_TYPE_XML, GstXMLClass))
  62
  63 typedef struct _GstXML GstXML;
  64 typedef struct _GstXMLClass GstXMLClass;
  65
  66 struct _GstXML
  67 {
  68   GstObject object;
  69
  70   /*< public > */
  71   GList *topelements;
  72
  73   xmlNsPtr ns;
  74
  75   /*< private > */
  76   gpointer _gst_reserved[GST_PADDING];
  77 };
  78
  79 struct _GstXMLClass
  80 {
  81   GstObjectClass parent_class;
  82
  83   /* signal callbacks */
  84   void (*object_loaded) (GstXML * xml, GstObject * object, xmlNodePtr self);
  85   void (*object_saved) (GstXML * xml, GstObject * object, xmlNodePtr self);
  86
  87   gpointer _gst_reserved[GST_PADDING];
  88 };
  89
  90 GType gst_xml_get_type (void);
  91 xmlDocPtr gst_xml_write (GstElement * element);
  92 gint gst_xml_write_file (GstElement * element, FILE * out);
  93 GstXML *gst_xml_new (void);
  94 gboolean gst_xml_parse_doc (GstXML * xml, xmlDocPtr doc, const guchar * root);
  95 gboolean gst_xml_parse_file (GstXML * xml, const guchar * fname,
  96     const guchar * root);
  97 gboolean gst_xml_parse_memory (GstXML * xml, guchar * buffer, guint size,
  98     const gchar * root);
  99 GstElement *gst_xml_get_element (GstXML * xml, const guchar * name);
 100 GList *gst_xml_get_topelements (GstXML * xml);
 101 GstElement *gst_xml_make_element (xmlNodePtr cur, GstObject * parent);
 102 #endif
 103 #endif
 104
 105 #if !defined(GST_DISABLE_LOADSAVE) && !defined(GST_REMOVE_DEPRECATED)
 106
 107 enum
 108 {
 109   OBJECT_LOADED,
 110   LAST_SIGNAL
 111 };
 112
 113 static void gst_xml_dispose (GObject * object);
 114
 115 static void gst_xml_object_loaded (GstObject * private, GstObject * object,
 116     xmlNodePtr self, gpointer data);
 117
 118 static GstObjectClass *parent_class = NULL;
 119 static guint gst_xml_signals[LAST_SIGNAL] = { 0 };
 120
 121 G_DEFINE_TYPE (GstXML, gst_xml, GST_TYPE_OBJECT);
 122
 123 static void
 124 gst_xml_class_init (GstXMLClass * klass)
 125 {
 126   GObjectClass *gobject_class = (GObjectClass *) klass;
 127
 128   parent_class = g_type_class_peek_parent (klass);
 129
 130   gobject_class->dispose = gst_xml_dispose;
 131
 132   /* FIXME G_TYPE_POINTER should be GType of xmlNodePtr
 133    * (ensonic) can't be fixed, as libxml does not use GObject (unfortunately)
 134    */
 135   /**
 136    * GstXML::object-loaded:
 137    * @xml: the xml persistence instance
 138    * @object: the object that has been loaded
 139    * @xml_node: the related xml_node pointer to the document tree
 140    *
 141    * Signals that a new object has been deserialized.
 142    */
 143   gst_xml_signals[OBJECT_LOADED] =
 144       g_signal_new ("object-loaded", G_TYPE_FROM_CLASS (klass),
 145       G_SIGNAL_RUN_LAST, G_STRUCT_OFFSET (GstXMLClass, object_loaded), NULL,
 146       NULL, gst_marshal_VOID__OBJECT_POINTER, G_TYPE_NONE, 2, GST_TYPE_OBJECT,
 147       G_TYPE_POINTER);
 148
 149 }
 150
 151 static void
 152 gst_xml_init (GstXML * xml)
 153 {
 154   xml->topelements = NULL;
 155 }
 156
 157 static void
 158 gst_xml_dispose (GObject * object)
 159 {
 160   GstXML *xml = GST_XML (object);
 161
 162   g_list_foreach (xml->topelements, (GFunc) gst_object_unref, NULL);
 163   g_list_free (xml->topelements);
 164   xml->topelements = NULL;
 165
 166   G_OBJECT_CLASS (parent_class)->dispose (object);
 167 }
 168
 169 /**
 170  * gst_xml_new:
 171  *
 172  * Create a new GstXML parser object.
 173  *
 174  * Returns: a pointer to a new GstXML object.
 175  */
 176 GstXML *
 177 gst_xml_new (void)
 178 {
 179   return GST_XML (g_object_newv (GST_TYPE_XML, 0, NULL));
 180 }
 181
 182 /**
 183  * gst_xml_write:
 184  * @element: The element to write out
 185  *
 186  * Converts the given element into an XML presentation.
 187  *
 188  * Returns: a pointer to an XML document
 189  */
 190 xmlDocPtr
 191 gst_xml_write (GstElement * element)
 192 {
 193   xmlDocPtr doc;
 194   xmlNodePtr elementnode;
 195   xmlNsPtr gst_ns;
 196
 197   doc = xmlNewDoc ((xmlChar *) "1.0");
 198
 199   doc->xmlRootNode = xmlNewDocNode (doc, NULL, (xmlChar *) "gstreamer", NULL);
 200
 201   gst_ns =
 202       xmlNewNs (doc->xmlRootNode,
 203       (xmlChar *) "http://gstreamer.net/gst-core/1.0/", (xmlChar *) "gst");
 204
 205   elementnode = xmlNewChild (doc->xmlRootNode, gst_ns, (xmlChar *) "element",
 206       NULL);
 207
 208   gst_object_save_thyself (GST_OBJECT (element), elementnode);
 209
 210   return doc;
 211 }
 212
 213 /**
 214  * gst_xml_write_file:
 215  * @element: The element to write out
 216  * @out: an open file, like stdout
 217  *
 218  * Converts the given element into XML and writes the formatted XML to an open
 219  * file.
 220  *
 221  * Returns: number of bytes written on success, -1 otherwise.
 222  */
 223 gint
 224 gst_xml_write_file (GstElement * element, FILE * out)
 225 {
 226   xmlDocPtr cur;
 227
 228 #ifdef HAVE_LIBXML2
 229   xmlOutputBufferPtr buf;
 230 #endif
 231   const char *encoding;
 232   xmlCharEncodingHandlerPtr handler = NULL;
 233   int indent;
 234   gboolean ret;
 235
 236   cur = gst_xml_write (element);
 237   if (!cur)
 238     return -1;
 239
 240 #ifdef HAVE_LIBXML2
 241   encoding = (const char *) cur->encoding;
 242
 243   if (encoding != NULL) {
 244     xmlCharEncoding enc;
 245
 246     enc = xmlParseCharEncoding (encoding);
 247
 248     if (cur->charset != XML_CHAR_ENCODING_UTF8) {
 249       xmlGenericError (xmlGenericErrorContext,
 250           "xmlDocDump: document not in UTF8\n");
 251       return -1;
 252     }
 253     if (enc != XML_CHAR_ENCODING_UTF8) {
 254       handler = xmlFindCharEncodingHandler (encoding);
 255       if (handler == NULL) {
 256         xmlFree ((char *) cur->encoding);
 257         cur->encoding = NULL;
 258       }
 259     }
 260   }
 261
 262   buf = xmlOutputBufferCreateFile (out, handler);
 263
 264   indent = xmlIndentTreeOutput;
 265   xmlIndentTreeOutput = 1;
 266   ret = xmlSaveFormatFileTo (buf, cur, NULL, 1);
 267   xmlIndentTreeOutput = indent;
 268 #else
 269   /* apparently this doesn't return anything in libxml1 */
 270   xmlDocDump (out, cur);
 271   ret = 1;
 272 #endif
 273
 274   return ret;
 275 }
 276
 277 /**
 278  * gst_xml_parse_doc:
 279  * @xml: a pointer to a GstXML object
 280  * @doc: a pointer to an xml document to parse
 281  * @root: The name of the root object to build
 282  *
 283  * Fills the GstXML object with the elements from the
 284  * xmlDocPtr.
 285  *
 286  * Returns: TRUE on success, FALSE otherwise
 287  */
 288 gboolean
 289 gst_xml_parse_doc (GstXML * xml, xmlDocPtr doc, const guchar * root)
 290 {
 291   xmlNodePtr field, cur;
 292   xmlNsPtr ns;
 293
 294   cur = xmlDocGetRootElement (doc);
 295   if (cur == NULL) {
 296     g_warning ("gstxml: empty document\n");
 297     return FALSE;
 298   }
 299   ns = xmlSearchNsByHref (doc, cur,
 300       (xmlChar *) "http://gstreamer.net/gst-core/1.0/");
 301   if (ns == NULL) {
 302     g_warning ("gstxml: document of wrong type, core namespace not found\n");
 303     return FALSE;
 304   }
 305   if (strcmp ((char *) cur->name, "gstreamer")) {
 306     g_warning ("gstxml: XML file is in wrong format\n");
 307     return FALSE;
 308   }
 309
 310   gst_class_signal_connect (GST_OBJECT_CLASS (G_OBJECT_GET_CLASS (xml)),
 311       "object_loaded", (gpointer) gst_xml_object_loaded, xml);
 312
 313   xml->ns = ns;
 314
 315   field = cur->xmlChildrenNode;
 316
 317   while (field) {
 318     if (!strcmp ((char *) field->name, "element") && (field->ns == xml->ns)) {
 319       GstElement *element;
 320
 321       element = gst_xml_make_element (field, NULL);
 322
 323       xml->topelements = g_list_prepend (xml->topelements, element);
 324     }
 325     field = field->next;
 326   }
 327
 328   xml->topelements = g_list_reverse (xml->topelements);
 329
 330   return TRUE;
 331 }
 332
 333 /* FIXME 0.9: Why guchar*? */
 334 /**
 335  * gst_xml_parse_file:
 336  * @xml: a pointer to a GstXML object
 337  * @fname: The filename with the xml description
 338  * @root: The name of the root object to build
 339  *
 340  * Fills the GstXML object with the corresponding elements from
 341  * the XML file fname. Optionally it will only build the element from
 342  * the element node root (if it is not NULL). This feature is useful
 343  * if you only want to build a specific element from an XML file
 344  * but not the pipeline it is embedded in.
 345  *
 346  * Pass "-" as fname to read from stdin. You can also pass a URI
 347  * of any format that libxml supports, including http.
 348  *
 349  * Returns: TRUE on success, FALSE otherwise
 350  */
 351 gboolean
 352 gst_xml_parse_file (GstXML * xml, const guchar * fname, const guchar * root)
 353 {
 354   xmlDocPtr doc;
 355   gboolean ret;
 356
 357   g_return_val_if_fail (fname != NULL, FALSE);
 358
 359   doc = xmlParseFile ((char *) fname);
 360
 361   if (!doc) {
 362     g_warning ("gstxml: XML file \"%s\" could not be read\n", fname);
 363     return FALSE;
 364   }
 365
 366   ret = gst_xml_parse_doc (xml, doc, root);
 367
 368   xmlFreeDoc (doc);
 369   return ret;
 370 }
 371
 372 /* FIXME 0.9: guchar* */
 373 /**
 374  * gst_xml_parse_memory:
 375  * @xml: a pointer to a GstXML object
 376  * @buffer: a pointer to the in memory XML buffer
 377  * @size: the size of the buffer
 378  * @root: the name of the root objects to build
 379  *
 380  * Fills the GstXML object with the corresponding elements from
 381  * an in memory XML buffer.
 382  *
 383  * Returns: TRUE on success
 384  */
 385 gboolean
 386 gst_xml_parse_memory (GstXML * xml, guchar * buffer, guint size,
 387     const gchar * root)
 388 {
 389   xmlDocPtr doc;
 390   gboolean ret;
 391
 392   g_return_val_if_fail (buffer != NULL, FALSE);
 393
 394   doc = xmlParseMemory ((char *) buffer, size);
 395
 396   ret = gst_xml_parse_doc (xml, doc, (const xmlChar *) root);
 397
 398   xmlFreeDoc (doc);
 399   return ret;
 400 }
 401
 402 static void
 403 gst_xml_object_loaded (GstObject * private, GstObject * object, xmlNodePtr self,
 404     gpointer data)
 405 {
 406   GstXML *xml = GST_XML (data);
 407
 408   /* FIXME check that this element was created from the same xmlDocPtr... */
 409   g_signal_emit (xml, gst_xml_signals[OBJECT_LOADED], 0, object, self);
 410 }
 411
 412 /**
 413  * gst_xml_get_topelements:
 414  * @xml: The GstXML to get the elements from
 415  *
 416  * Retrieve a list of toplevel elements.
 417  *
 418  * Returns: a GList of top-level elements. The caller does not own a copy
 419  * of the list and must not free or modify the list. The caller also does not
 420  * own a reference to any of the elements in the list and should obtain its own
 421  * reference using gst_object_ref() if necessary.
 422  */
 423 GList *
 424 gst_xml_get_topelements (GstXML * xml)
 425 {
 426   g_return_val_if_fail (xml != NULL, NULL);
 427
 428   return xml->topelements;
 429 }
 430
 431 /* FIXME 0.11: why is the arg guchar* instead of gchar*? */
 432 /**
 433  * gst_xml_get_element:
 434  * @xml: The GstXML to get the element from
 435  * @name: The name of element to retrieve
 436  *
 437  * This function is used to get a pointer to the GstElement corresponding
 438  * to name in the pipeline description. You would use this if you have
 439  * to do anything to the element after loading.
 440  *
 441  * Returns: a pointer to a new GstElement, caller owns returned reference.
 442  */
 443 GstElement *
 444 gst_xml_get_element (GstXML * xml, const guchar * name)
 445 {
 446   GstElement *element;
 447   GList *topelements;
 448
 449   g_return_val_if_fail (xml != NULL, NULL);
 450   g_return_val_if_fail (name != NULL, NULL);
 451
 452   GST_DEBUG ("gstxml: getting element \"%s\"", name);
 453
 454   topelements = gst_xml_get_topelements (xml);
 455
 456   while (topelements) {
 457     GstElement *top = GST_ELEMENT (topelements->data);
 458
 459     GST_DEBUG ("gstxml: getting element \"%s\"", name);
 460     if (!strcmp (GST_ELEMENT_NAME (top), (char *) name)) {
 461       return GST_ELEMENT_CAST (gst_object_ref (top));
 462     } else {
 463       if (GST_IS_BIN (top)) {
 464         element = gst_bin_get_by_name (GST_BIN (top), (gchar *) name);
 465
 466         if (element)
 467           return element;
 468       }
 469     }
 470     topelements = g_list_next (topelements);
 471   }
 472   return NULL;
 473 }
 474
 475 /**
 476  * gst_xml_make_element:
 477  * @cur: the xml node
 478  * @parent: the parent of this object when it's loaded
 479  *
 480  * Load the element from the XML description
 481  *
 482  * Returns: the new element
 483  */
 484 GstElement *
 485 gst_xml_make_element (xmlNodePtr cur, GstObject * parent)
 486 {
 487   xmlNodePtr children = cur->xmlChildrenNode;
 488   GstElement *element;
 489   gchar *name = NULL;
 490   gchar *type = NULL;
 491
 492   /* first get the needed tags to construct the element */
 493   while (children) {
 494     if (!strcmp ((char *) children->name, "name")) {
 495       name = (gchar *) xmlNodeGetContent (children);
 496     } else if (!strcmp ((char *) children->name, "type")) {
 497       type = (gchar *) xmlNodeGetContent (children);
 498     }
 499     children = children->next;
 500   }
 501   g_return_val_if_fail (name != NULL, NULL);
 502   g_return_val_if_fail (type != NULL, NULL);
 503
 504   GST_CAT_INFO (GST_CAT_XML, "loading \"%s\" of type \"%s\"", name, type);
 505
 506   element = gst_element_factory_make (type, name);
 507
 508   g_return_val_if_fail (element != NULL, NULL);
 509
 510   g_free (type);
 511   g_free (name);
 512
 513   /* ne need to set the parent on this object bacause the pads */
 514   /* will go through the hierarchy to link to their peers */
 515   if (parent) {
 516     if (GST_IS_BIN (parent)) {
 517       gst_bin_add (GST_BIN (parent), element);
 518     } else {
 519       gst_object_set_parent (GST_OBJECT (element), parent);
 520     }
 521   }
 522
 523   gst_object_restore_thyself (GST_OBJECT (element), cur);
 524
 525   return element;
 526 }
 527
 528 #else
 529
 530 /* FIXME: keep this dummy _get_type function around for now, so
 531  * gobject-introspection doesn't fail in the GST_REMOVE_DEPRECATED and
 532  * GST_DISABLE_LOADSAVE case */
 533 GType gst_xml_get_type (void);
 534
 535 GType
 536 gst_xml_get_type (void)
 537 {
 538   return g_pointer_type_register_static ("GstXML");
 539 }
 540
 541 #endif