## 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);
    gboolean            (*GstPluginInitFullFunc)            (GstPlugin *plugin,
                                                             gpointer user_data);
    #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);
    const GstStructure* gst_plugin_get_cache_data           (GstPlugin *plugin);
    void                gst_plugin_set_cache_data           (GstPlugin *plugin,
                                                             GstStructure *cache_data);
    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,
                                                             const gchar *description,
                                                             GstPluginInitFunc init_func,
                                                             const gchar *version,
                                                             const gchar *license,
                                                             const gchar *source,
                                                             const gchar *package,
                                                             const gchar *origin);
    gboolean            gst_plugin_register_static_full     (gint major_version,
                                                             gint minor_version,
                                                             const gchar *name,
                                                             const gchar *description,
                                                             GstPluginInitFullFunc init_full_func,
                                                             const gchar *version,
                                                             const gchar *license,
                                                             const gchar *source,
                                                             const gchar *package,
                                                             const gchar *origin,
                                                             gpointer user_data);

    enum                GstPluginFlags;
    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;
      const gchar *description;
      GstPluginInitFunc plugin_init;
      const gchar *version;
      const gchar *license;
      const gchar *source;
      const gchar *package;
      const gchar *origin;
      const gchar *release_datetime;
    } 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
const 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
const gchar *`release_datetime`; | date time string in ISO 8601 format (or rather, a subset thereof), or NULL. Allowed are the following formats: "YYYY-MM-DD" and "YYY-MM-DDTHH:MMZ" (with 'T' a separator and 'Z' indicating UTC/Zulu time). This field should be set via the GST_PACKAGE_RELEASE_DATETIME preprocessor macro (Since: 0.10.31)

### 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. One would then register each GstPluginFeature.

`plugin` : | The plugin object
Returns : | `TRUE` if plugin initialised successfully

### GstPluginInitFullFunc ()

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

A plugin should provide a pointer to a function of either GstPluginInitFunc or this type in the plugin_desc struct. The function will be called by the loader at startup. One would then register each GstPluginFeature. This version allows user data to be passed to init function (useful for bindings).

`plugin` : | The plugin object
`user_data` : | extra data
Returns : | `TRUE` if plugin initialised successfully

Since 0.10.24

### 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. When using autoconf, this is usually set automatically via the AC_INIT macro, and set in config.h. If you are not using autoconf, you will need to define PACKAGE yourself and set it to a short mnemonic string identifying your application/package, e.g. 'someapp' or 'my-plugins-foo.

If defined, the GST_PACKAGE_RELEASE_DATETIME will also be used for the GstPluginDesc,release_datetime 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_get_cache_data ()

    const GstStructure* gst_plugin_get_cache_data           (GstPlugin *plugin);

Gets the plugin specific data cache. If it is `NULL` there is no cached data stored. This is the case when the registry is getting rebuilt.

`plugin` : | a plugin
Returns : | The cached data as a GstStructure or `NULL`.

Since 0.10.24

### gst_plugin_set_cache_data ()

    void                gst_plugin_set_cache_data           (GstPlugin *plugin,
                                                             GstStructure *cache_data);

Adds plugin specific data to cache. Passes the ownership of the structure to the `plugin`.

The cache is flushed every time the registry is rebuilt.

`plugin` : | a plugin
`cache_data` : | a structure containing the data to cache

Since 0.10.24

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

### gst_plugin_register_static_full ()

    gboolean            gst_plugin_register_static_full     (gint major_version,
                                                             gint minor_version,
                                                             const gchar *name,
                                                             const gchar *description,
                                                             GstPluginInitFullFunc init_full_func,
                                                             const gchar *version,
                                                             const gchar *license,
                                                             const gchar *source,
                                                             const gchar *package,
                                                             const gchar *origin,
                                                             gpointer user_data);

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) with a GstPluginInitFullFunc which allows user data to be passed to the callback function (useful for bindings).

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_full_func` : | pointer to the init function with user data 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
`user_data` : | gpointer to user data
Returns : | TRUE if the plugin was registered correctly, otherwise FALSE.

Since 0.10.24

### enum GstPluginFlags

    typedef enum
    {
      GST_PLUGIN_FLAG_CACHED = (1<<0),
      GST_PLUGIN_FLAG_BLACKLISTED = (1<<1)
    } GstPluginFlags;

The plugin loading state

`GST_PLUGIN_FLAG_CACHED` | Temporarily loaded plugins
`GST_PLUGIN_FLAG_BLACKLISTED` | The plugin won't be scanned (again)

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