## GstPlugin GstPlugin — Container for features loaded from a shared object module |

## Synopsis

    #include <gst/gst.h>

    GQuark              gst_plugin_error_quark              (void);
    #define             GST_PLUGIN_ERROR
    enum                GstPluginError;
                        GstPlugin;
                        GstPluginDesc;
    gboolean            (*GstPluginInitFunc)                (GstPlugin *plugin);
    #define             GST_PLUGIN_DEFINE                   (major,minor,name,description,init,version,license,package,origin)
    #define             GST_PLUGIN_DEFINE_STATIC            (major,minor,name,description,init,version,license,package,origin)
    #define             GST_LICENSE_UNKNOWN
    gboolean            (*GstPluginFilter)                  (GstPlugin *plugin,
                                                             gpointer user_data);
    const gchar*        gst_plugin_get_name                 (GstPlugin *plugin);
    const gchar*        gst_plugin_get_description          (GstPlugin *plugin);
    const gchar*        gst_plugin_get_filename             (GstPlugin *plugin);
    const gchar*        gst_plugin_get_license              (GstPlugin *plugin);
    const gchar*        gst_plugin_get_package              (GstPlugin *plugin);
    const gchar*        gst_plugin_get_origin               (GstPlugin *plugin);
    const gchar*        gst_plugin_get_source               (GstPlugin *plugin);
    const gchar*        gst_plugin_get_version              (GstPlugin *plugin);
    GModule *           gst_plugin_get_module               (GstPlugin *plugin);
    gboolean            gst_plugin_is_loaded                (GstPlugin *plugin);
    gboolean            gst_plugin_name_filter              (GstPlugin *plugin,
                                                             const gchar *name);
    GstPlugin *         gst_plugin_load_file                (const gchar *filename,
                                                             GError **error);
    GstPlugin *         gst_plugin_load                     (GstPlugin *plugin);
    GstPlugin *         gst_plugin_load_by_name             (const gchar *name);
    void                gst_plugin_list_free                (GList *list);
    gboolean            gst_plugin_register_static          (gint major_version,
                                                             gint minor_version,
                                                             const gchar *name,
                                                             gchar *description,
                                                             GstPluginInitFunc init_func,
                                                             const gchar *version,
                                                             const gchar *license,
                                                             const gchar *source,
                                                             const gchar *package,
                                                             const gchar *origin);

    enum                GstPluginDependencyFlags;
    void                gst_plugin_add_dependency           (GstPlugin *plugin,
                                                             const gchar **env_vars,
                                                             const gchar **paths,
                                                             const gchar **names,
                                                             GstPluginDependencyFlags flags);
    void                gst_plugin_add_dependency_simple    (GstPlugin *plugin,
                                                             const gchar *env_vars,
                                                             const gchar *paths,
                                                             const gchar *names,
                                                             GstPluginDependencyFlags flags);

## Object Hierarchy

      GObject
       +----GstObject
             +----GstPlugin

## Description

GStreamer is extensible, so GstElement instances can be loaded at runtime. A plugin system can provide one or more of the basic GStreamer GstPluginFeature subclasses.

A plugin should export a symbol gst_plugin_desc that is a struct of type GstPluginDesc. the plugin loader will check the version of the core library the plugin was linked against and will create a new GstPlugin. It will then call the GstPluginInitFunc function that was provided in the gst_plugin_desc.

Once you have a handle to a GstPlugin (e.g. from the GstRegistry), you can add any object that subclasses GstPluginFeature.

Usually plugins are always automaticlly loaded so you don't need to call `gst_plugin_load()` explicitly to bring it into memory. There are options to statically link plugins to an app or even use GStreamer without a plugin repository in which case `gst_plugin_load()` can be needed to bring the plugin into memory.

## Details

### gst_plugin_error_quark ()

    GQuark              gst_plugin_error_quark              (void);

Get the error quark.

Returns : | The error quark used in GError messages

### GST_PLUGIN_ERROR

    #define GST_PLUGIN_ERROR gst_plugin_error_quark ()

The error message category quark

### enum GstPluginError

    typedef enum
    {
      GST_PLUGIN_ERROR_MODULE,
      GST_PLUGIN_ERROR_DEPENDENCIES,
      GST_PLUGIN_ERROR_NAME_MISMATCH
    } GstPluginError;

The plugin loading errors

`GST_PLUGIN_ERROR_MODULE` | The plugin could not be loaded
`GST_PLUGIN_ERROR_DEPENDENCIES` | The plugin has unresolved dependencies
`GST_PLUGIN_ERROR_NAME_MISMATCH` | The plugin has already be loaded from a different file

### GstPlugin

    typedef struct _GstPlugin GstPlugin;

The plugin object

### GstPluginDesc

    typedef struct {
      gint major_version;
      gint minor_version;
      const gchar *name;
      gchar *description;
      GstPluginInitFunc plugin_init;
      const gchar *version;
      const gchar *license;
      const gchar *source;
      const gchar *package;
      const gchar *origin;

      gpointer _gst_reserved[GST_PADDING];
    } GstPluginDesc;

A plugin should export a variable of this type called plugin_desc. The plugin loader will use the data provided there to initialize the plugin.

The `licence` parameter must be one of: LGPL, GPL, QPL, GPL/QPL, MPL, BSD, MIT/X11, Proprietary, unknown.

gint `major_version`; | the major version number of core that plugin was compiled for
gint `minor_version`; | the minor version number of core that plugin was compiled for
const gchar *`name`; | a unique name of the plugin
gchar *`description`; | description of plugin
GstPluginInitFunc `plugin_init`; | pointer to the init function of this plugin.
const gchar *`version`; | version of the plugin
const gchar *`license`; | effective license of plugin
const gchar *`source`; | source module plugin belongs to
const gchar *`package`; | shipped package plugin belongs to
const gchar *`origin`; | URL to provider of plugin
gpointer `_gst_reserved`[GST_PADDING]; | private, for later expansion

### GstPluginInitFunc ()

    gboolean            (*GstPluginInitFunc)                (GstPlugin *plugin);

A plugin should provide a pointer to a function of this type in the plugin_desc struct. This function will be called by the loader at startup.

`plugin` : | The plugin object that can be used to register GstPluginFeatures for this plugin.
Returns : | `TRUE` if plugin initialised successfully

### GST_PLUGIN_DEFINE()

    #define             GST_PLUGIN_DEFINE(major,minor,name,description,init,version,license,package,origin)

This macro needs to be used to define the entry point and meta data of a plugin. One would use this macro to export a plugin, so that it can be used by other applications.

The macro uses a define named PACKAGE for the GstPluginDesc,source field.

`major` : | major version number of the gstreamer-core that plugin was compiled for
`minor` : | minor version number of the gstreamer-core that plugin was compiled for
`name` : | short, but unique name of the plugin
`description` : | information about the purpose of the plugin
`init` : | function pointer to the plugin_init method with the signature of `static gboolean plugin_init (GstPlugin * plugin)`.
`version` : | full version string (e.g. VERSION from config.h)
`license` : | under which licence the package has been released, e.g. GPL, LGPL.
`package` : | the package-name (e.g. PACKAGE_NAME from config.h)
`origin` : | a description from where the package comes from (e.g. the homepage URL)

### GST_PLUGIN_DEFINE_STATIC()

    #define             GST_PLUGIN_DEFINE_STATIC(major,minor,name,description,init,version,license,package,origin)

### Warning

`GST_PLUGIN_DEFINE_STATIC` is deprecated and should not be used in newly-written code. Use `gst_plugin_register_static()` instead. This macro was deprecated because it uses constructors, which is a compiler feature not available on all compilers.

This macro needs to be used to define the entry point and meta data of a local plugin. One would use this macro to define a local plugin that can only be used by the own application.

The macro uses a define named PACKAGE for the GstPluginDesc.source field.

`major` : | major version number of the gstreamer-core that plugin was compiled for
`minor` : | minor version number of the gstreamer-core that plugin was compiled for
`name` : | short, but unique name of the plugin
`description` : | information about the purpose of the plugin
`init` : | function pointer to the plugin_init method with the signature of `static gboolean plugin_init (GstPlugin * plugin)`.
`version` : | full version string (e.g. VERSION from config.h)
`license` : | under which licence the package has been released, e.g. GPL, LGPL.
`package` : | the package-name (e.g. PACKAGE_NAME from config.h)
`origin` : | a description from where the package comes from (e.g. the homepage URL)

### GST_LICENSE_UNKNOWN

    #define GST_LICENSE_UNKNOWN "unknown"

To be used in GST_PLUGIN_DEFINE or GST_PLUGIN_DEFINE_STATIC if usure about the licence.

### GstPluginFilter ()

    gboolean            (*GstPluginFilter)                  (GstPlugin *plugin,
                                                             gpointer user_data);

A function that can be used with e.g. `gst_registry_plugin_filter()` to get a list of plugins that match certain criteria.

`plugin` : | the plugin to check
`user_data` : | the user_data that has been passed on e.g. `gst_registry_plugin_filter()`
Returns : | TRUE for a positive match, FALSE otherwise

### gst_plugin_get_name ()

    const gchar*        gst_plugin_get_name                 (GstPlugin *plugin);

Get the short name of the plugin

`plugin` : | plugin to get the name of
Returns : | the name of the plugin

### gst_plugin_get_description ()

    const gchar*        gst_plugin_get_description          (GstPlugin *plugin);

Get the long descriptive name of the plugin

`plugin` : | plugin to get long name of
Returns : | the long name of the plugin

### gst_plugin_get_filename ()

    const gchar*        gst_plugin_get_filename             (GstPlugin *plugin);

get the filename of the plugin

`plugin` : | plugin to get the filename of
Returns : | the filename of the plugin

### gst_plugin_get_license ()

    const gchar*        gst_plugin_get_license              (GstPlugin *plugin);

get the license of the plugin

`plugin` : | plugin to get the license of
Returns : | the license of the plugin

### gst_plugin_get_package ()

    const gchar*        gst_plugin_get_package              (GstPlugin *plugin);

get the package the plugin belongs to.

`plugin` : | plugin to get the package of
Returns : | the package of the plugin

### gst_plugin_get_origin ()

    const gchar*        gst_plugin_get_origin               (GstPlugin *plugin);

get the URL where the plugin comes from

`plugin` : | plugin to get the origin of
Returns : | the origin of the plugin

### gst_plugin_get_source ()

    const gchar*        gst_plugin_get_source               (GstPlugin *plugin);

get the source module the plugin belongs to.

`plugin` : | plugin to get the source of
Returns : | the source of the plugin

### gst_plugin_get_version ()

    const gchar*        gst_plugin_get_version              (GstPlugin *plugin);

get the version of the plugin

`plugin` : | plugin to get the version of
Returns : | the version of the plugin

### gst_plugin_get_module ()

    GModule *           gst_plugin_get_module               (GstPlugin *plugin);

Gets the GModule of the plugin. If the plugin isn't loaded yet, NULL is returned.

`plugin` : | plugin to query
Returns : | module belonging to the plugin or NULL if the plugin isn't loaded yet.

### gst_plugin_is_loaded ()

    gboolean            gst_plugin_is_loaded                (GstPlugin *plugin);

queries if the plugin is loaded into memory

`plugin` : | plugin to query
Returns : | TRUE is loaded, FALSE otherwise

### gst_plugin_name_filter ()

    gboolean            gst_plugin_name_filter              (GstPlugin *plugin,
                                                             const gchar *name);

A standard filter that returns TRUE when the plugin is of the given name.

`plugin` : | the plugin to check
`name` : | the name of the plugin
Returns : | TRUE if the plugin is of the given name.

### gst_plugin_load_file ()

    GstPlugin *         gst_plugin_load_file                (const gchar *filename,
                                                             GError **error);

Loads the given plugin and refs it. Caller needs to unref after use.

`filename` : | the plugin filename to load
`error` : | pointer to a NULL-valued GError
Returns : | a reference to the existing loaded GstPlugin, a reference to the newly-loaded GstPlugin, or NULL if an error occurred.

### gst_plugin_load ()

    GstPlugin *         gst_plugin_load                     (GstPlugin *plugin);

Loads `plugin`. Note that the *return value* is the loaded plugin; `plugin` is untouched. The normal use pattern of this function goes like this:

    GstPlugin *loaded_plugin;
    loaded_plugin = gst_plugin_load (plugin);
    // presumably, we're no longer interested in the potentially-unloaded plugin
    gst_object_unref (plugin);
    plugin = loaded_plugin;

`plugin` : | plugin to load
Returns : | A reference to a loaded plugin, or NULL on error.

### gst_plugin_load_by_name ()

    GstPlugin *         gst_plugin_load_by_name             (const gchar *name);

Load the named plugin. Refs the plugin.

`name` : | name of plugin to load
Returns : | A reference to a loaded plugin, or NULL on error.

### gst_plugin_list_free ()

    void                gst_plugin_list_free                (GList *list);

Unrefs each member of `list`, then frees the list.

`list` : | list of GstPlugin

### gst_plugin_register_static ()

    gboolean            gst_plugin_register_static          (gint major_version,
                                                             gint minor_version,
                                                             const gchar *name,
                                                             gchar *description,
                                                             GstPluginInitFunc init_func,
                                                             const gchar *version,
                                                             const gchar *license,
                                                             const gchar *source,
                                                             const gchar *package,
                                                             const gchar *origin);

Registers a static plugin, ie. a plugin which is private to an application or library and contained within the application or library (as opposed to being shipped as a separate module file).

You must make sure that GStreamer has been initialised (with `gst_init()` or via `gst_init_get_option_group()`) before calling this function.

`major_version` : | the major version number of the GStreamer core that the plugin was compiled for, you can just use GST_VERSION_MAJOR here
`minor_version` : | the minor version number of the GStreamer core that the plugin was compiled for, you can just use GST_VERSION_MINOR here
`name` : | a unique name of the plugin (ideally prefixed with an application- or library-specific namespace prefix in order to avoid name conflicts in case a similar plugin with the same name ever gets added to GStreamer)
`description` : | description of the plugin
`init_func` : | pointer to the init function of this plugin.
`version` : | version string of the plugin
`license` : | effective license of plugin. Must be one of the approved licenses (see GstPluginDesc above) or the plugin will not be registered.
`source` : | source module plugin belongs to
`package` : | shipped package plugin belongs to
`origin` : | URL to provider of plugin
Returns : | TRUE if the plugin was registered correctly, otherwise FALSE.

Since 0.10.16

### enum GstPluginDependencyFlags

    typedef enum {
      GST_PLUGIN_DEPENDENCY_FLAG_NONE = 0,
      GST_PLUGIN_DEPENDENCY_FLAG_RECURSE = (1 << 0),
      GST_PLUGIN_DEPENDENCY_FLAG_PATHS_ARE_DEFAULT_ONLY = (1 << 1),
      GST_PLUGIN_DEPENDENCY_FLAG_FILE_NAME_IS_SUFFIX = (1 << 2)
    } GstPluginDependencyFlags;

Flags used in connection with `gst_plugin_add_dependency()`.

`GST_PLUGIN_DEPENDENCY_FLAG_NONE` | no special flags
`GST_PLUGIN_DEPENDENCY_FLAG_RECURSE` | recurse into subdirectories
`GST_PLUGIN_DEPENDENCY_FLAG_PATHS_ARE_DEFAULT_ONLY` | use paths argument only if none of the environment variables is set
`GST_PLUGIN_DEPENDENCY_FLAG_FILE_NAME_IS_SUFFIX` | interpret filename argument as filter suffix and check all matching files in the directory

Since 0.10.22

### gst_plugin_add_dependency ()

    void                gst_plugin_add_dependency           (GstPlugin *plugin,
                                                             const gchar **env_vars,
                                                             const gchar **paths,
                                                             const gchar **names,
                                                             GstPluginDependencyFlags flags);

Make GStreamer aware of external dependencies which affect the feature set of this plugin (ie. the elements or typefinders associated with it).

GStreamer will re-inspect plugins with external dependencies whenever any of the external dependencies change. This is useful for plugins which wrap other plugin systems, e.g. a plugin which wraps a plugin-based visualisation library and makes visualisations available as GStreamer elements, or a codec loader which exposes elements and/or caps dependent on what external codec libraries are currently installed.

`plugin` : | a GstPlugin
`env_vars` : | NULL-terminated array of environent variables affecting the feature set of the plugin (e.g. an environment variable containing paths where to look for additional modules/plugins of a library), or NULL. Environment variable names may be followed by a path component which will be added to the content of the environment variable, e.g. "HOME/.mystuff/plugins".
`paths` : | NULL-terminated array of directories/paths where dependent files may be.
`names` : | NULL-terminated array of file names (or file name suffixes, depending on `flags`) to be used in combination with the paths from `paths` and/or the paths extracted from the environment variables in `env_vars`, or NULL.
`flags` : | optional flags, or GST_PLUGIN_DEPENDENCY_FLAG_NONE

Since 0.10.22

### gst_plugin_add_dependency_simple ()

    void                gst_plugin_add_dependency_simple    (GstPlugin *plugin,
                                                             const gchar *env_vars,
                                                             const gchar *paths,
                                                             const gchar *names,
                                                             GstPluginDependencyFlags flags);

Make GStreamer aware of external dependencies which affect the feature set of this plugin (ie. the elements or typefinders associated with it).

GStreamer will re-inspect plugins with external dependencies whenever any of the external dependencies change. This is useful for plugins which wrap other plugin systems, e.g. a plugin which wraps a plugin-based visualisation library and makes visualisations available as GStreamer elements, or a codec loader which exposes elements and/or caps dependent on what external codec libraries are currently installed.

Convenience wrapper function for `gst_plugin_add_dependency()` which takes simple strings as arguments instead of string arrays, with multiple arguments separated by predefined delimiters (see above).

`plugin` : | the GstPlugin
`env_vars` : | one or more environent variables (separated by ':', ';' or ','), or NULL. Environment variable names may be followed by a path component which will be added to the content of the environment variable, e.g. "HOME/.mystuff/plugins:MYSTUFF_PLUGINS_PATH"
`paths` : | one ore more directory paths (separated by ':' or ';' or ','), or NULL. Example: "/usr/lib/mystuff/plugins"
`names` : | one or more file names or file name suffixes (separated by commas), or NULL
`flags` : | optional flags, or GST_PLUGIN_DEPENDENCY_FLAG_NONE

Since 0.10.22

## See Also

#GstPluginFeature, GstElementFactory