## 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;
                        GstParseContext;
    enum                GstParseFlags;
    GstElement *        gst_parse_launch                    (const gchar *pipeline_description,
                                                             GError **error);
    GstElement *        gst_parse_launch_full               (const gchar *pipeline_description,
                                                             GstParseContext *context,
                                                             GstParseFlags flags,
                                                             GError **error);
    GstElement *        gst_parse_launchv                   (const gchar **argv,
                                                             GError **error);
    GstElement *        gst_parse_launchv_full              (const gchar **argv,
                                                             GstParseContext *context,
                                                             GstParseFlags flags,
                                                             GError **error);
    GstElement *        gst_parse_bin_from_description      (const gchar *bin_description,
                                                             gboolean ghost_unlinked_pads,
                                                             GError **err);
    GstElement *        gst_parse_bin_from_description_full (const gchar *bin_description,
                                                             gboolean ghost_unlinked_pads,
                                                             GstParseContext *context,
                                                             GstParseFlags flags,
                                                             GError **err);

    GstParseContext *   gst_parse_context_new               (void);
    void                gst_parse_context_free              (GstParseContext *context);
    gchar **            gst_parse_context_get_missing_elements
                                                            (GstParseContext *context);

## Description

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

## 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

### GstParseContext

    typedef struct _GstParseContext GstParseContext;

Opaque structure.

Since 0.10.20

### enum GstParseFlags

    typedef enum
    {
      GST_PARSE_FLAG_NONE = 0,
      GST_PARSE_FLAG_FATAL_ERRORS = (1 << 0)
    } GstParseFlags;

Parsing options.

`GST_PARSE_FLAG_NONE` | Do not use any special parsing options.
`GST_PARSE_FLAG_FATAL_ERRORS` | Always return NULL when an error occurs (default behaviour is to return partially constructed bins or elements in some cases)

Since 0.10.20

### 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_launch_full ()

    GstElement *        gst_parse_launch_full               (const gchar *pipeline_description,
                                                             GstParseContext *context,
                                                             GstParseFlags flags,
                                                             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
`context` : | a parse context allocated with `gst_parse_context_new()`, or `NULL`
`flags` : | parsing options, or GST_PARSE_FLAG_NONE
`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 then is returned.

Since 0.10.20

### 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_launchv_full ()

    GstElement *        gst_parse_launchv_full              (const gchar **argv,
                                                             GstParseContext *context,
                                                             GstParseFlags flags,
                                                             GError **error);

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

`argv` : | null-terminated array of arguments
`context` : | a parse context allocated with `gst_parse_context_new()`, or `NULL`
`flags` : | parsing options, or GST_PARSE_FLAG_NONE
`error` : | pointer to a GError (which must be initialised to `NULL`)
Returns : | a new element on success; on failure, either `NULL` or a partially-constructed bin or element will be returned and `error` will be set (unless you passed GST_PARSE_FLAG_FATAL_ERRORS in `flags`, then `NULL` will always be returned on failure)

Since 0.10.20

### gst_parse_bin_from_description ()

    GstElement *        gst_parse_bin_from_description      (const gchar *bin_description,
                                                             gboolean ghost_unlinked_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 unlinked 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 unlinked source pads or multiple unlinked sink pads and want them all ghosted, you will have to create the ghost pads yourself).

`bin_description` : | command line describing the bin
`ghost_unlinked_pads` : | whether to automatically create ghost pads for unlinked 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

### gst_parse_bin_from_description_full ()

    GstElement *        gst_parse_bin_from_description_full (const gchar *bin_description,
                                                             gboolean ghost_unlinked_pads,
                                                             GstParseContext *context,
                                                             GstParseFlags flags,
                                                             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 unlinked 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 unlinked source pads or multiple unlinked sink pads and want them all ghosted, you will have to create the ghost pads yourself).

`bin_description` : | command line describing the bin
`ghost_unlinked_pads` : | whether to automatically create ghost pads for unlinked source or sink pads within the bin
`context` : | a parse context allocated with `gst_parse_context_new()`, or `NULL`
`flags` : | parsing options, or GST_PARSE_FLAG_NONE
`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.20

### gst_parse_context_new ()

    GstParseContext *   gst_parse_context_new               (void);

Allocates a parse context for use with `gst_parse_launch_full()` or `gst_parse_launchv_full()`.

Returns : | a newly-allocated parse context. Free with `gst_parse_context_free()` when no longer needed.

Since 0.10.20

### gst_parse_context_free ()

    void                gst_parse_context_free              (GstParseContext *context);

Frees a parse context previously allocated with `gst_parse_context_new()`.

`context` : | a GstParseContext

Since 0.10.20

### gst_parse_context_get_missing_elements ()

    gchar **            gst_parse_context_get_missing_elements
                                                            (GstParseContext *context);

Retrieve missing elements from a previous run of `gst_parse_launch_full()` or `gst_parse_launchv_full()`. Will only return results if an error code of `GST_PARSE_ERROR_NO_SUCH_ELEMENT` was returned.

`context` : | a GstParseContext
Returns : | a NULL-terminated array of element factory name strings of missing elements. Free with `g_strfreev()` when no longer needed.

Since 0.10.20