gnomemm r1696 - in gstreamermm/trunk: . gstreamer/gstreamermm gstreamer/src tools/m4

[jaalburqu svn gnome org]

Author: jaalburqu
Date: Wed Sep 10 02:25:41 2008
New Revision: 1696
URL: http://svn.gnome.org/viewvc/gnomemm?rev=1696&view=rev

Log:
2008-09-09  Josà Alburquerque  <jaalburqu svn gnome org>

	* gstreamer/src/xml.ccg:
	* gstreamer/src/xml.hg: Added class docs.  Made Gst::write_xml() and
	Gst::write_xml_file() static methods of Gst::XML renaming them to
	write() and write_to_stream() (similar to C API); also made
	Gst::make_element() a static member of Gst::XML.  Used libxml++ API
	where possible; used Glib::ustring instead of std::string where
	possible.
	* tools/m4/convert_gst.m4: Added Glib::ustring& and xmlpp::Document*
	conversions.

	* gstreamer/gstreamermm/object.cc:
	* gstreamer/gstreamermm/object.h: Added class and method docs.  Added
	save_thyself() and restore_thyself() (saving and restoring to/from XML
	using libxml++).

	* configure.ac: Added libxml++-2.6 as build dependency for
	gstreamerbasemm (which is needed to build gstreamerbasemm classes
	derived from Gst::Object).

	* gstreamer/src/caps.ccg:
	* gstreamer/src/caps.hg: Renamed save() and load() to save_thyself()
	and load_thyself() respectively (as in C API).

Modified:
   gstreamermm/trunk/ChangeLog
   gstreamermm/trunk/configure.ac
   gstreamermm/trunk/gstreamer/gstreamermm/object.cc
   gstreamermm/trunk/gstreamer/gstreamermm/object.h
   gstreamermm/trunk/gstreamer/src/caps.ccg
   gstreamermm/trunk/gstreamer/src/caps.hg
   gstreamermm/trunk/gstreamer/src/xml.ccg
   gstreamermm/trunk/gstreamer/src/xml.hg
   gstreamermm/trunk/tools/m4/convert_gst.m4

Modified: gstreamermm/trunk/configure.ac
==============================================================================
--- gstreamermm/trunk/configure.ac	(original)
+++ gstreamermm/trunk/configure.ac	Wed Sep 10 02:25:41 2008
@@ -144,6 +144,7 @@
         gstreamer-plugins-base-0.10 >= ${gstreamermm_min_gst_version} \
         gstreamer-audio-0.10 >= ${gstreamermm_min_gst_version} \
         gstreamer-interfaces-0.10 >= ${gstreamermm_min_gst_version} \
+        libxml++-2.6 >= ${gstreamermm_min_libxmlpp_version} \
         )
 AC_SUBST(GSTREAMERBASEMM_CFLAGS)
 AC_SUBST(GSTREAMERBASEMM_LIBS)

Modified: gstreamermm/trunk/gstreamer/gstreamermm/object.cc
==============================================================================
--- gstreamermm/trunk/gstreamer/gstreamermm/object.cc	(original)
+++ gstreamermm/trunk/gstreamer/gstreamermm/object.cc	Wed Sep 10 02:25:41 2008
@@ -128,6 +128,11 @@
   return gst_object_set_name(gobj(), name.c_str());
 }
 
+bool Object::set_name()
+{
+  return gst_object_set_name(gobj(), NULL);
+}
+
 Glib::ustring Object::get_name() const
 {
   return Glib::convert_return_gchar_ptr_to_ustring(gst_object_get_name(const_cast<GstObject*>(gobj())));
@@ -163,6 +168,19 @@
   gst_object_set_name_prefix(gobj(), prefix.c_str()); 
 }
 
+xmlpp::Node* Object::save_thyself(xmlpp::Node* parent) const
+{
+  gst_object_save_thyself(const_cast<GstObject*>(gobj()), parent->cobj());
+
+  // gst_object_save_thyself() returns parent node so do so here also.
+  return parent;
+}
+
+void Object::restore_thyself(xmlpp::Node* self)
+{
+  gst_object_restore_thyself(gobj(), self->cobj());
+}
+
 #ifdef GLIBMM_PROPERTIES_ENABLED
 Glib::PropertyProxy<Glib::ustring> Object::property_name() 
 {

Modified: gstreamermm/trunk/gstreamer/gstreamermm/object.h
==============================================================================
--- gstreamermm/trunk/gstreamer/gstreamermm/object.h	(original)
+++ gstreamermm/trunk/gstreamer/gstreamermm/object.h	Wed Sep 10 02:25:41 2008
@@ -23,6 +23,7 @@
 
 #include <glibmm.h>
 #include <glibmm/object.h>
+#include <libxml++/nodes/node.h>
 
 
 #ifndef DOXYGEN_SHOULD_SKIP_THIS
@@ -43,7 +44,26 @@
 //so that we can add code to the Object(GObject*) constructor.
 //(If this becomes difficult then we might add a _CUSTOM_CAST_CTOR() macro to gmmproc).
 
-/** TODO: Add documentation.
+//TODO: Paragraphs about floating references their effect on elements and how
+//to handle them using gst_object_ref() and gst_object_sink() are not included
+//in class docs below.  Should they be?
+
+/** Gst::Object â Base class for the GStreamer object hierarchy.
+ * Gst::Object provides a root for the object hierarchy tree filed in by the
+ * GStreamer library. It is currently a thin wrapper on top of Glib::Object.
+ * It is an abstract class that is not very usable on its own.
+ *
+ * Gst::Object gives us basic refcounting, parenting functionality and
+ * locking. Most of the function are just extended for special GStreamer needs
+ * and can be found under the same name in the base class of Gst::Object which
+ * is Glib::Object (e.g. Glib::Object::reference() becomes
+ * Gst:Object::reference().
+ *
+ * In contrast to Glib::Object instances, Gst::Object adds a name property.
+ * The functions set_name() and get_name() are used to set/get the name of the
+ * object.
+ *
+ * Last reviewed on 2005-11-09 (0.9.4)
  *
  */
 class Object : public Glib::Object 
@@ -96,19 +116,87 @@
   //Note that gst_object_ref() and gst_object_unref() just call the GObject functions, with some extra debug logging.
   void reference() const;
   void unreference() const;
-
   
+  /** Sets the name of object.  For setting an arbitrary name, use set_name()
+   * with no argument.  This function makes a copy of the provided name, so the
+   * caller retains ownership of the name it sent.
+   *
+   * @param name New name of object.
+   * @return true if the name could be set. Since Objects that have a parent
+   * cannot be renamed, this function returns false in those cases. MT safe.
+   * This function grabs and releases object's LOCK. 
+   */
   bool set_name(const Glib::ustring& name);
+
+  /** Gives object a guaranteed unique name.
+   * 
+   * @return true if the name could be set. Since Objects that have a parent
+   * cannot be renamed, this function returns false in those cases. MT safe.
+   * This function grabs and releases object's LOCK. 
+   */
+  bool set_name();
+
+  /** Returns a copy of the name of object. For a nameless object, this
+   * returns NULL.
+   *
+   * @return The name of object. MT safe. This function grabs and releases
+   * object's LOCK. 
+   */
   Glib::ustring get_name() const;
   
+  //TODO: floating reference comment not included in set_parent() method docs
+  //below.
+  /** Sets the parent of object to parent. The object's reference count will
+   * be incremented.
+   *
+   * This function causes the parent-set signal to be emitted when the parent
+   * was successfully set.
+   *
+   * @param parent New parent of object.
+   * @return true if parent could be set or false when object already had a
+   * parent or object and parent are the same. MT safe. Grabs and releases
+   * object's LOCK.
+   */
   bool set_parent(const Glib::RefPtr<Object>& parent);
+
+  /** Returns the parent of object. 
+   *
+   * @return Parent of object, this can be NULL if object has no parent. MT
+   * safe. Grabs and releases object's LOCK.
+   */
   Glib::RefPtr<Object> get_parent();
+
+  /** Returns the parent of object. 
+   *
+   * @return Parent of object, this can be NULL if object has no parent. MT
+   * safe. Grabs and releases object's LOCK.
+   */
   Glib::RefPtr<const Object> get_parent() const;
 
-  
+  /** Clear the parent of object, removing the associated reference. This
+   * function decreases the refcount of object.
+   *
+   * MT safe. Grabs and releases object's lock.
+   */
   void unparent();
   
+  /** Returns a copy of the name prefix of object. For a prefixless object,
+   * this returns NULL.
+   *
+   * @return The name prefix of object. MT safe. This function grabs and
+   * releases object's LOCK. 
+   */
   Glib::ustring get_name_prefix() const;
+
+  /** Sets the name prefix of object to name_prefix. This function makes a
+   * copy of the provided name prefix, so the caller retains ownership of the
+   * name prefix it sent.
+   *
+   * MT safe. This function grabs and releases object's LOCK.
+   *
+   * @param name_prefix New name prefix of object.
+   *
+   */
   void set_name_prefix(const Glib::ustring& prefix);
 
   //TODO: Is this useful? (Note that the .def needs to be fixed by hand): _WRAP_SIGNAL(void deep_notify(Glib::RefPtr<Object> prop_object, GParamSpec* prop), "deep-notify")
@@ -116,6 +204,17 @@
   //TODO: When the C signal registration has been fixed: _WRAP_SIGNAL(void parent_set(Glib::RefPtr<Object> parent), "parent-set")
   //TODO: When the C signal registration has been fixed: _WRAP_SIGNAL(void parent_unset(Glib::RefPtr<Object> parent), "parent-unset")
 
+  /** Saves object into the parent XML node.
+   * @param parent The parent XML node to save object into.
+   * @return The new xmlpp::Node pointer with the saved object
+   */
+  xmlpp::Node* save_thyself(xmlpp::Node* parent) const;
+
+  /** Restores the Gst::Object with the data from the parent XML node.
+   * @param self The XML node to load object from.
+   */
+  void restore_thyself(xmlpp::Node* self);
+
   #ifdef GLIBMM_PROPERTIES_ENABLED
   /** The name of the object.
    *

Modified: gstreamermm/trunk/gstreamer/src/caps.ccg
==============================================================================
--- gstreamermm/trunk/gstreamer/src/caps.ccg	(original)
+++ gstreamermm/trunk/gstreamer/src/caps.ccg	Wed Sep 10 02:25:41 2008
@@ -104,7 +104,7 @@
   //return Glib::wrap(gobj(), true);
 }
 
-xmlpp::Node* Caps::save(xmlpp::Node* parent) const
+xmlpp::Node* Caps::save_thyself(xmlpp::Node* parent) const
 {
   gst_caps_save_thyself(gobj(), parent->cobj());
 

Modified: gstreamermm/trunk/gstreamer/src/caps.hg
==============================================================================
--- gstreamermm/trunk/gstreamer/src/caps.hg	(original)
+++ gstreamermm/trunk/gstreamer/src/caps.hg	Wed Sep 10 02:25:41 2008
@@ -166,10 +166,10 @@
    * @param parent A XML parent node.
    * @return The parent XML Node.
    */
-  xmlpp::Node* save(xmlpp::Node* parent) const;
+  xmlpp::Node* save_thyself(xmlpp::Node* parent) const;
   _IGNORE(gst_caps_save_thyself)
 
-  _WRAP_METHOD(static Glib::RefPtr<Caps> load(xmlpp::Node* parent), gst_caps_load_thyself)
+  _WRAP_METHOD(static Glib::RefPtr<Caps> load_thyself(xmlpp::Node* parent), gst_caps_load_thyself)
 
   _WRAP_METHOD(Glib::ustring to_string() const, gst_caps_to_string)
 

Modified: gstreamermm/trunk/gstreamer/src/xml.ccg
==============================================================================
--- gstreamermm/trunk/gstreamer/src/xml.ccg	(original)
+++ gstreamermm/trunk/gstreamer/src/xml.ccg	Wed Sep 10 02:25:41 2008
@@ -19,10 +19,6 @@
  * Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
  */
 
-#include <fcntl.h>
-#include <errno.h>
-#include <sys/types.h>
-#include <sys/stat.h>
 #include <gst/gstxml.h>
 #include <gstreamermm/element.h>
 
@@ -32,31 +28,26 @@
 namespace Gst
 {
 
-bool XML::parse_memory(const std::string& buffer, const std::string& root)
+bool XML::parse_memory(const std::string& buffer, const Glib::ustring& root)
 {
   return gst_xml_parse_memory(this->gobj(),(guchar*)(buffer.c_str()), buffer.size(), root.c_str());
 }
 
-xmlDocPtr write_xml(const Glib::RefPtr<Element>& element)
+xmlDocPtr XML::write(const Glib::RefPtr<Element>& element)
 {
   return gst_xml_write(element->gobj());
 }
 
-int write_xml_file(const Glib::RefPtr<Element>& element, const std::string& filename)
+void XML::write_to_stream(const Glib::RefPtr<Element>& element, std::ostream& out)
 {
-  int file = creat(filename.c_str(), O_EXCL);
-  int result = gst_xml_write_file(element->gobj(),(FILE*) file);
-  int errsv = errno;
-  close(file);
-  if(result == -1)
-    throw Glib::FileError(Glib::FileError::Code(errsv), "failed to write xml file: '" + filename + "'");
-  else
-    return result;
-}
+  xmlDocPtr xmlDoc = write(element);
+  xmlpp::Node rootNode(xmlDocGetRootElement(xmlDoc));
 
-Glib::RefPtr<Element> make_element(const xmlNodePtr& xml_node, const Glib::RefPtr<Object>& parent)
-{
-  return Glib::wrap(gst_xml_make_element(xml_node, parent->gobj()));
+  xmlpp::Document doc;
+  doc.create_root_node_by_import(&rootNode);
+  doc.write_to_stream_formatted(out);
+
+  xmlFreeDoc(xmlDoc);
 }
 
 } //namespace Gst

Modified: gstreamermm/trunk/gstreamer/src/xml.hg
==============================================================================
--- gstreamermm/trunk/gstreamer/src/xml.hg	(original)
+++ gstreamermm/trunk/gstreamer/src/xml.hg	Wed Sep 10 02:25:41 2008
@@ -21,6 +21,7 @@
 
 #include <gst/gstxml.h>
 #include <gstreamermm/object.h>
+#include <libxml++/document.h>
 
 _DEFS(gstreamermm,gst)
 
@@ -29,6 +30,15 @@
 
 class Element;
 
+/** Gst::XML â XML save/restore operations of pipelines.
+ * GStreamer pipelines can be saved to xml files using write_to_stream(). They
+ * can be loaded back using parse_doc() / parse_file() / parse_memory().
+ * Additionally one can load saved pipelines into the gst-editor to inspect
+ * the graph.
+ *
+ * Gst::Element implementations need to override Gst::Object::save_thyself()
+ * and Gst::Object::restore_thyself().
+ */
 class XML : public Object
 {
   _CLASS_GOBJECT(XML, GstXML, GST_XML, Object, GstObject)
@@ -39,8 +49,22 @@
 public:
   _WRAP_CREATE()
 
-  _WRAP_METHOD(bool parse_doc(xmlDocPtr doc, const std::string& root), gst_xml_parse_doc)
-  _WRAP_METHOD(bool parse_file(const std::string& filename, const std::string& root), gst_xml_parse_file)
+  /** Converts the given element into an XML presentation.
+   * @param element The element to write out.
+   * @return A pointer to an XML document.
+   */
+  static xmlDocPtr write(const Glib::RefPtr<Element>& element);
+
+  /** Converts the given element into XML and writes the formatted XML to an
+   * open output stream.
+   *
+   * @param element The element to write out.
+   * @param out an open std::ostream, like std::cout.
+   */
+  static void write_to_stream(const Glib::RefPtr<Element>& element, std::ostream& out);
+
+  _WRAP_METHOD(bool parse_doc(xmlpp::Document* doc, Glib::ustring& root), gst_xml_parse_doc)
+  _WRAP_METHOD(bool parse_file(const std::string& filename, const Glib::ustring& root), gst_xml_parse_file)
 
   /** Fills the Gst::XML object with the corresponding elements from an in
    * memory XML buffer.
@@ -49,11 +73,11 @@
    * @param root The name of the root objects to build.
    * @return true on success.
    */
-  bool parse_memory(const std::string& buffer, const std::string& root);
+  bool parse_memory(const std::string& buffer, const Glib::ustring& root);
 
-  //Note: gst_xml_get_element() returns a reference.
-  _WRAP_METHOD(Glib::RefPtr<Element> get_element(const std::string& name), gst_xml_get_element)
-  _WRAP_METHOD(Glib::RefPtr<const Element> get_element(const std::string& name) const, gst_xml_get_element, constversion)
+  //Note: gst_xml_get_element() returns a reference (GstElement*).
+  _WRAP_METHOD(Glib::RefPtr<Element> get_element(const Glib::ustring& name), gst_xml_get_element)
+  _WRAP_METHOD(Glib::RefPtr<const Element> get_element(const Glib::ustring& name) const, gst_xml_get_element, constversion)
 
 #m4 _CONVERSION(`GList*',`Glib::ListHandle< Glib::RefPtr<Element> >',`$2($3, Glib::OWNERSHIP_NONE)')
   _WRAP_METHOD(Glib::ListHandle< Glib::RefPtr<Element> > get_topelements(), gst_xml_get_topelements)
@@ -61,14 +85,13 @@
 #m4 _CONVERSION(`GList*',`Glib::ListHandle< Glib::RefPtr<const Element> >',`$2($3, Glib::OWNERSHIP_NONE)')
   _WRAP_METHOD(Glib::ListHandle< Glib::RefPtr<const Element> > get_topelements() const, gst_xml_get_topelements)
 
+  _WRAP_METHOD(static Glib::RefPtr<Element> make_element(xmlpp::Node* curr, const Glib::RefPtr<Gst::Object>& parent), gst_xml_make_element)
+
   _IGNORE(gst_xml_parse_memory)
 
 #m4 _CONVERSION(`GstObject*',`const Glib::RefPtr<Gst::Object>&',`Glib::wrap($3, true)')
   _WRAP_SIGNAL(void object_loaded(const Glib::RefPtr<Gst::Object>& object, xmlNode* xml_node), "object-loaded")
 };
 
-xmlDocPtr write_xml(const Glib::RefPtr<Element>& element);
-int write_xml_file(const Glib::RefPtr<Element>& element, const std::string& filename);
-Glib::RefPtr<Element> make_element(const xmlNodePtr& xml_node, const Glib::RefPtr<Object>& parent);
 
 } //namespace Gst

Modified: gstreamermm/trunk/tools/m4/convert_gst.m4
==============================================================================
--- gstreamermm/trunk/tools/m4/convert_gst.m4	(original)
+++ gstreamermm/trunk/tools/m4/convert_gst.m4	Wed Sep 10 02:25:41 2008
@@ -176,9 +176,11 @@
 _CONVERSION(`Glib::StaticRecMutex&',`GStaticRecMutex*',`($3).gobj()')
 
 #String Conversions
-_CONVERSION(`const std::string&',`const guchar*',`(const guchar*) ($3.c_str())')
+_CONVERSION(`const std::string&',`const guchar*',`(($2)($3).c_str())')
 _CONVERSION(`gchar*',`const Glib::ustring&',__GCHARP_TO_USTRING)
 _CONVERSION(`const gchar*',`const Glib::ustring&',__GCHARP_TO_USTRING)
+_CONVERSION(`Glib::ustring&',`const guchar*', (($2)($3).c_str()))
 
 #libxml++ Conversions
 _CONVERSION(`xmlpp::Node*',`xmlNodePtr',`($3)->cobj()')
+_CONVERSION(`xmlpp::Document*',`xmlDocPtr',`($3)->cobj()')