## GstParse

GstParse — Get a pipeline from a text pipeline description

## Synopsis

    #include <gst/gst.h>

    GQuark              gst_parse_error_quark               (void);
    #define             GST_PARSE_ERROR
    enum                GstParseError;
    GstElement*         gst_parse_launch                    (const gchar *pipeline_description,
                                                             GError **error);
    GstElement*         gst_parse_launchv                   (const gchar **argv,
                                                             GError **error);
    GstElement*         gst_parse_bin_from_description      (const gchar *bin_description,
                                                             gboolean ghost_unconnected_pads,
                                                             GError **err);

## Description

These function allow to create a pipeline based on the syntax used in the gst-launch utillity.

## Details

### gst_parse_error_quark ()

    GQuark              gst_parse_error_quark               (void);

Get the error quark used by the parsing subsystem.

Returns : | the quark of the parse errors.

### GST_PARSE_ERROR

    #define GST_PARSE_ERROR gst_parse_error_quark ()

Get access to the error quark of the parse subsystem.

### enum GstParseError

    typedef enum
    {
      GST_PARSE_ERROR_SYNTAX,
      GST_PARSE_ERROR_NO_SUCH_ELEMENT,
      GST_PARSE_ERROR_NO_SUCH_PROPERTY,
      GST_PARSE_ERROR_LINK,
      GST_PARSE_ERROR_COULD_NOT_SET_PROPERTY,
      GST_PARSE_ERROR_EMPTY_BIN,
      GST_PARSE_ERROR_EMPTY
    } GstParseError;

The different parsing errors that can occur.

`GST_PARSE_ERROR_SYNTAX` | A syntax error occured.
`GST_PARSE_ERROR_NO_SUCH_ELEMENT` | The description contained an unknown element
`GST_PARSE_ERROR_NO_SUCH_PROPERTY` | An element did not have a specified property
`GST_PARSE_ERROR_LINK` | There was an error linking two pads.
`GST_PARSE_ERROR_COULD_NOT_SET_PROPERTY` | There was an error setting a property
`GST_PARSE_ERROR_EMPTY_BIN` | An empty bin was specified.
`GST_PARSE_ERROR_EMPTY` | An empty description was specified

### gst_parse_launch ()

    GstElement*         gst_parse_launch                    (const gchar *pipeline_description,
                                                             GError **error);

Create a new pipeline based on command line syntax. Please note that you might get a return value that is not `NULL` even though the `error` is set. In this case there was a recoverable parsing error and you can try to play the pipeline.

`pipeline_description` : | the command line describing the pipeline
`error` : | the error message in case of an erroneous pipeline.
Returns : | a new element on success, `NULL` on failure. If more than one toplevel element is specified by the `pipeline_description`, all elements are put into a GstPipeline, which than is returned.

### gst_parse_launchv ()

    GstElement*         gst_parse_launchv                   (const gchar **argv,
                                                             GError **error);

Create a new element based on command line syntax. `error` will contain an error message if an erroneuos pipeline is specified. An error does not mean that the pipeline could not be constructed.

`argv` : | null-terminated array of arguments
`error` : | pointer to a GError
Returns : | a new element on success and `NULL` on failure.

### gst_parse_bin_from_description ()

    GstElement*         gst_parse_bin_from_description      (const gchar *bin_description,
                                                             gboolean ghost_unconnected_pads,
                                                             GError **err);

This is a convenience wrapper around `gst_parse_launch()` to create a GstBin from a gst-launch-style pipeline description. See `gst_parse_launch()` and the gst-launch man page for details about the syntax. Ghost pads on the bin for unconnected source or sink pads within the bin can automatically be created (but only a maximum of one ghost pad for each direction will be created; if you expect multiple unconnected source pads or multiple unconnected sink pads and want them all ghosted, you will have to create the ghost pads yourself).

`bin_description` : | command line describing the bin
`ghost_unconnected_pads` : | whether to automatically create ghost pads for unconnected source or sink pads within the bin
`err` : | where to store the error message in case of an error, or NULL
Returns : | a newly-created bin, or NULL if an error occurred.

Since 0.10.3