GstXML

GstXML — XML save/restore operations of pipelines

Synopsis


#include <gst/gst.h>

                    GstXML;
xmlDocPtr           gst_xml_write                       (GstElement *element);
gint                gst_xml_write_file                  (GstElement *element,
                                                         FILE *out);
GstXML*             gst_xml_new                         (void);
gboolean            gst_xml_parse_doc                   (GstXML *xml,
                                                         xmlDocPtr doc,
                                                         const guchar *root);
gboolean            gst_xml_parse_file                  (GstXML *xml,
                                                         const guchar *fname,
                                                         const guchar *root);
gboolean            gst_xml_parse_memory                (GstXML *xml,
                                                         guchar *buffer,
                                                         guint size,
                                                         const gchar *root);
GstElement*         gst_xml_get_element                 (GstXML *xml,
                                                         const guchar *name);
GList*              gst_xml_get_topelements             (GstXML *xml);
GstElement*         gst_xml_make_element                (xmlNodePtr cur,
                                                         GstObject *parent);

Object Hierarchy

  GObject
   +----GstObject
         +----GstXML

Signals

  "object-loaded"                                  : Run Last

Description

GStreamer pipelines can be saved to xml files using gst_xml_write_file(). They can be loaded back using gst_xml_parse_doc() / gst_xml_parse_file() / gst_xml_parse_memory(). Additionally one can load saved pipelines into the gst-editor to inspect the graph.

GstElement implementations need to override the save_thyself() and restore_thyself() virtual functions of GstObject.

Details

GstXML

typedef struct {
  GList      *topelements;

  xmlNsPtr ns;
} GstXML;

XML parser object

GList *topelements;

list of element nodes

xmlNsPtr ns;

name space

gst_xml_write ()

xmlDocPtr           gst_xml_write                       (GstElement *element);

Converts the given element into an XML presentation.

element :

The element to write out

Returns :

a pointer to an XML document

gst_xml_write_file ()

gint                gst_xml_write_file                  (GstElement *element,
                                                         FILE *out);

Converts the given element into XML and writes the formatted XML to an open file.

element :

The element to write out

out :

an open file, like stdout

Returns :

number of bytes written on success, -1 otherwise.

gst_xml_new ()

GstXML*             gst_xml_new                         (void);

Create a new GstXML parser object.

Returns :

a pointer to a new GstXML object.

gst_xml_parse_doc ()

gboolean            gst_xml_parse_doc                   (GstXML *xml,
                                                         xmlDocPtr doc,
                                                         const guchar *root);

Fills the GstXML object with the elements from the xmlDocPtr.

xml :

a pointer to a GstXML object

doc :

a pointer to an xml document to parse

root :

The name of the root object to build

Returns :

TRUE on success, FALSE otherwise

gst_xml_parse_file ()

gboolean            gst_xml_parse_file                  (GstXML *xml,
                                                         const guchar *fname,
                                                         const guchar *root);

Fills the GstXML object with the corresponding elements from the XML file fname. Optionally it will only build the element from the element node root (if it is not NULL). This feature is useful if you only want to build a specific element from an XML file but not the pipeline it is embedded in.

Pass "-" as fname to read from stdin. You can also pass a URI of any format that libxml supports, including http.

xml :

a pointer to a GstXML object

fname :

The filename with the xml description

root :

The name of the root object to build

Returns :

TRUE on success, FALSE otherwise

gst_xml_parse_memory ()

gboolean            gst_xml_parse_memory                (GstXML *xml,
                                                         guchar *buffer,
                                                         guint size,
                                                         const gchar *root);

Fills the GstXML object with the corresponding elements from an in memory XML buffer.

xml :

a pointer to a GstXML object

buffer :

a pointer to the in memory XML buffer

size :

the size of the buffer

root :

the name of the root objects to build

Returns :

TRUE on success

gst_xml_get_element ()

GstElement*         gst_xml_get_element                 (GstXML *xml,
                                                         const guchar *name);

This function is used to get a pointer to the GstElement corresponding to name in the pipeline description. You would use this if you have to do anything to the element after loading.

xml :

The GstXML to get the element from

name :

The name of element to retrieve

Returns :

a pointer to a new GstElement, caller owns returned reference.

gst_xml_get_topelements ()

GList*              gst_xml_get_topelements             (GstXML *xml);

Retrieve a list of toplevel elements.

xml :

The GstXML to get the elements from

Returns :

a GList of top-level elements. The caller does not own a copy of the list and must not free or modify the list. The caller also does not own a reference to any of the elements in the list and should obtain its own reference using gst_object_ref() if necessary.

gst_xml_make_element ()

GstElement*         gst_xml_make_element                (xmlNodePtr cur,
                                                         GstObject *parent);

Load the element from the XML description

cur :

the xml node

parent :

the parent of this object when it's loaded

Returns :

the new element

Signal Details

The "object-loaded" signal

void                user_function                      (GstXML    *xml,
                                                        GstObject *object,
                                                        gpointer   xml_node,
                                                        gpointer   user_data)      : Run Last

Signals that a new object has been deserialized.

xml :

the xml persistence instance

object :

the object that has been loaded

xml_node :

the related xml_node pointer to the document tree

user_data :

user data set when the signal handler was connected.