## GstPlugin

GstPlugin — Container for features loaded from a shared object module

## Synopsis

    GQuark      gst_plugin_error_quark          (void);
    #define     GST_PLUGIN_ERROR
    enum        GstPluginError;
    struct      GstPlugin;
    struct      GstPluginDesc;
    gboolean    (*GstPluginInitFunc)            (GstPlugin *plugin);
    void        (*GstPluginExitFunc)            (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);
    #define     GST_TYPE_PLUGIN
    G_CONST_RETURN gchar* gst_plugin_get_name   (GstPlugin *plugin);
    G_CONST_RETURN gchar* gst_plugin_get_description
                                                (GstPlugin *plugin);
    G_CONST_RETURN gchar* gst_plugin_get_filename
                                                (GstPlugin *plugin);
    G_CONST_RETURN gchar* gst_plugin_get_license
                                                (GstPlugin *plugin);
    G_CONST_RETURN gchar* gst_plugin_get_package
                                                (GstPlugin *plugin);
    G_CONST_RETURN gchar* gst_plugin_get_origin (GstPlugin *plugin);
    GModule*    gst_plugin_get_module           (GstPlugin *plugin);
    gboolean    gst_plugin_is_loaded            (GstPlugin *plugin);
    GList*      gst_plugin_feature_filter       (GstPlugin *plugin,
                                                 GstPluginFeatureFilter filter,
                                                 gboolean first,
                                                 gpointer user_data);
    GList*      gst_plugin_list_feature_filter  (GList *list,
                                                 GstPluginFeatureFilter filter,
                                                 gboolean first,
                                                 gpointer user_data);
    gboolean    gst_plugin_name_filter          (GstPlugin *plugin,
                                                 const gchar *name);
    GList*      gst_plugin_get_feature_list     (GstPlugin *plugin);
    GstPluginFeature* gst_plugin_find_feature   (GstPlugin *plugin,
                                                 const gchar *name,
                                                 GType type);
    gboolean    gst_plugin_check_file           (const gchar *filename,
                                                 GError **error);
    GstPlugin*  gst_plugin_load_file            (const gchar *filename,
                                                 GError **error);
    gboolean    gst_plugin_unload_plugin        (GstPlugin *plugin);
    void        gst_plugin_add_feature          (GstPlugin *plugin,
                                                 GstPluginFeature *feature);
    gboolean    gst_plugin_load                 (const gchar *name);
    gboolean    gst_library_load                (const gchar *name);

## Description

GStreamer is extensible so `GstElements` 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 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 plugin_desc.

Once you have a handle to a GstPlugin, you can add any object that subclasses GstPluginFeature.

use `gst_plugin_find_feature()` and `gst_plugin_get_feature_list()` to find features in a plugin.

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

### struct GstPlugin

    struct GstPlugin {

      GstPluginDesc	desc;

      gchar *	filename;
      GList *	features;		/* list of features provided */
      gint 		numfeatures;

      gpointer 	manager;		/* managing registry */
      GModule *	module;			/* contains the module if the plugin is loaded */

      gpointer _gst_reserved[GST_PADDING];
    };

The plugin object

### struct GstPluginDesc

    struct GstPluginDesc {

      gint major_version;			/* major version of core that plugin was compiled for */
      gint minor_version;			/* minor version of core that plugin was compiled for */
      gchar *name;				/* unique name of plugin */
      gchar *description;			/* description of plugin */
      GstPluginInitFunc plugin_init;	/* pointer to plugin_init function */
      GstPluginExitFunc plugin_exit;	/* pointer to exiting function */
      gchar *version;			/* version of the plugin */
      gchar *license;			/* effective license of plugin */
      gchar *package;			/* package plugin belongs to */
      gchar *origin;			/* URL to provider of plugin */

      gpointer _gst_reserved[GST_PADDING];
    };

A plugins should export a variable of this type called plugin_desc. This plugin loaded will use this variable to initialize the plugin.

gint `major_version` | The minor version of the gstreamer library this plugin was created with
gint `minor_version` | The minor version of the gstreamer library this plugin was created with
gchar *`name` | The name of the plugin
gchar *`description` |
GstPluginInitFunc `plugin_init` | The init function of this plugin.
GstPluginExitFunc `plugin_exit` |
gchar *`version` |
gchar *`license` |
gchar *`package` |
gchar *`origin` |
gpointer `_gst_reserved`[GST_PADDING] |

### GstPluginInitFunc ()

    gboolean    (*GstPluginInitFunc)            (GstPlugin *plugin);

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

`plugin` : | The plugin object that can be used to register stuff for this plugin.
Returns : | A boolean indicating success or failure.

### GstPluginExitFunc ()

    void        (*GstPluginExitFunc)            (GstPlugin *plugin);

`plugin` : |

### GST_PLUGIN_DEFINE()

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

`major` : |
`minor` : |
`name` : |
`description` : |
`init` : |
`version` : |
`license` : |
`package` : |
`origin` : |

### GST_PLUGIN_DEFINE_STATIC()

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

`major` : |
`minor` : |
`name` : |
`description` : |
`init` : |
`version` : |
`license` : |
`package` : |
`origin` : |

### GST_LICENSE_UNKNOWN

    #define GST_LICENSE_UNKNOWN "unknown"

### GstPluginFilter ()

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

`plugin` : |
`user_data` : |
Returns : |

### GST_TYPE_PLUGIN

    #define GST_TYPE_PLUGIN   (gst_plugin_get_type())

### gst_plugin_get_name ()

    G_CONST_RETURN 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 ()

    G_CONST_RETURN 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 ()

    G_CONST_RETURN 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 ()

    G_CONST_RETURN 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 ()

    G_CONST_RETURN 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 ()

    G_CONST_RETURN 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_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_feature_filter ()

    GList*      gst_plugin_feature_filter       (GstPlugin *plugin,
                                                 GstPluginFeatureFilter filter,
                                                 gboolean first,
                                                 gpointer user_data);

`plugin` : |
`filter` : |
`first` : |
`user_data` : |
Returns : |

### gst_plugin_list_feature_filter ()

    GList*      gst_plugin_list_feature_filter  (GList *list,
                                                 GstPluginFeatureFilter filter,
                                                 gboolean first,
                                                 gpointer user_data);

`list` : |
`filter` : |
`first` : |
`user_data` : |
Returns : |

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

    GList*      gst_plugin_get_feature_list     (GstPlugin *plugin);

get a list of all the features that this plugin provides

`plugin` : | the plugin to get the features from
Returns : | a GList of features, use g_list_free to free the list.

### gst_plugin_find_feature ()

    GstPluginFeature* gst_plugin_find_feature   (GstPlugin *plugin,
                                                 const gchar *name,
                                                 GType type);

Find a feature of the given name and type in the given plugin.

`plugin` : | plugin to get the feature from
`name` : | The name of the feature to find
`type` : | The type of the feature to find
Returns : | a GstPluginFeature or NULL if the feature was not found.

### gst_plugin_check_file ()

    gboolean    gst_plugin_check_file           (const gchar *filename,
                                                 GError **error);

Checks if the given path represents a GStreamer plugin.

`filename` : | the plugin filename to check for pluginness
`error` : | pointer to a NULL-valued GError
Returns : | TRUE if the given path is a GStreamer plugin.

### gst_plugin_load_file ()

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

Loads the given plugin.

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

### gst_plugin_unload_plugin ()

    gboolean    gst_plugin_unload_plugin        (GstPlugin *plugin);

Unload the given plugin.

`plugin` : | The plugin to unload
Returns : | whether or not the plugin unloaded

### gst_plugin_add_feature ()

    void        gst_plugin_add_feature          (GstPlugin *plugin,
                                                 GstPluginFeature *feature);

Add feature to the list of those provided by the plugin. There is a separate namespace for each plugin feature type. See gst_plugin_get_feature_list

`plugin` : | plugin to add feature to
`feature` : | feature to add

### gst_plugin_load ()

    gboolean    gst_plugin_load                 (const gchar *name);

Load the named plugin.

`name` : | name of plugin to load
Returns : | whether the plugin was loaded or not

### gst_library_load ()

    gboolean    gst_library_load                (const gchar *name);

Load the named library. Name should be given as "liblibrary.so".

`name` : | name of library to load
Returns : | whether the library was loaded or not

## See Also

GstPluginFeature, GstType, GstAutoplug, GstElementFactory