GstParse

## 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 (see man-page for syntax documentation).

Please note that these functions take several measures to create somewhat dynamic pipelines. Due to that such pipelines are not always reusable (set the state to NULL and back to PLAYING).

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

### enum GstParseFlags

    typedef enum {
      GST_PARSE_FLAG_NONE = 0,
      GST_PARSE_FLAG_FATAL_ERRORS = (1 << 0),
      GST_PARSE_FLAG_NO_SINGLE_ELEMENT_BINS = (1 << 1)
    } 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)
`GST_PARSE_FLAG_NO_SINGLE_ELEMENT_BINS` | If a bin only has a single element, just return the element.

### 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. [transfer floating]

### 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`. [allow-none]
`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. [transfer floating]

### 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. [in][array zero-terminated=1]
`error` : | pointer to a GError
Returns : | a new element on success and `NULL` on failure. [transfer floating]

### 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. [in][array zero-terminated=1]
`context` : | a parse context allocated with `gst_parse_context_new()`, or `NULL`. [allow-none]
`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). [transfer floating]

### 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. [transfer floating][type Gst.Bin]

### 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`. [transfer none][allow-none]
`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 element, which is guaranteed to be a bin unless GST_FLAG_NO_SINGLE_ELEMENT_BINS was passed, or `NULL` if an error occurred. [transfer full][type Gst.Element]

### 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()`.

Free-function: gst_parse_context_free

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

### 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. [transfer full]

### 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. [transfer full][array zero-terminated=1][element-type gchar*]