## GstPlugin

GstPlugin — Dynamically loadable Elements

## Synopsis

    #include <gst/gst.h>

    #define     GST_PLUGIN_ERROR
    GQuark      gst_plugin_error_quark          (void);
    enum        GstPluginError;
    struct      GstPlugin;
    gboolean    (*GstPluginInitFunc)            (GModule *module,
                                                 GstPlugin *plugin);
    struct      GstPluginDesc;
    #define     GST_PLUGIN_DESC                 (major,minor,name,init)
    #define     GST_PLUGIN_DESC_DYNAMIC         (major,minor,name,init)
    #define     GST_PLUGIN_DESC_STATIC          (major,minor,name,init)
    GstPlugin*  gst_plugin_new                  (const gchar *filename);
    void        gst_plugin_set_name             (GstPlugin *plugin,
                                                 const gchar *name);
    const gchar* gst_plugin_get_name            (GstPlugin *plugin);
    const gchar* gst_plugin_get_longname        (GstPlugin *plugin);
    void        gst_plugin_set_longname         (GstPlugin *plugin,
                                                 const gchar *longname);
    const gchar* gst_plugin_get_filename        (GstPlugin *plugin);
    gboolean    gst_plugin_is_loaded            (GstPlugin *plugin);
    GList*      gst_plugin_get_feature_list     (GstPlugin *plugin);
    GstPluginFeature* gst_plugin_find_feature   (GstPlugin *plugin,
                                                 const gchar *name,
                                                 GType type);
    gboolean    gst_plugin_load_plugin          (GstPlugin *plugin,
                                                 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

    #define GST_PLUGIN_ERROR gst_plugin_error_quark ()

The error quark

### gst_plugin_error_quark ()

    GQuark      gst_plugin_error_quark          (void);

Get the error quark

Returns : | The error quark used in GError messages

### enum GstPluginError

    typedef enum
    {
      GST_PLUGIN_ERROR_MODULE,
      GST_PLUGIN_ERROR_DEPENDENCIES
    } GstPluginError;

The plugin loading errors

`GST_PLUGIN_ERROR_MODULE` | The plugin could not be loaded
`GST_PLUGIN_ERROR_DEPENDENCIES` | The plugin has unresolved dependencies

### struct GstPlugin

    struct GstPlugin {

      gchar 	*name;			/* name of the plugin */
      gchar 	*longname;		/* long name of plugin */
      gchar 	*filename;		/* filename it came from */

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

      gpointer 	 manager;		/* managing registry */
      GModule 	*module;		/* contains the module if the plugin is loaded */
      gboolean	 init_called;		/* if the init function has been called */
    };

The plugin object

### GstPluginInitFunc ()

    gboolean    (*GstPluginInitFunc)            (GModule *module,
                                                 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.

`module` : | The `GModule` it was loaded from
`plugin` : | The plugin object that can be used to register stuff for this plugin.
Returns : | A boolean indicating success or failure.

### 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;        /* name of plugin */
      GstPluginInitFunc plugin_init; /* pointer to plugin_init function */
    };

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
GstPluginInitFunc `plugin_init` | The init function of this plugin.

### GST_PLUGIN_DESC()

    #define     GST_PLUGIN_DESC(major,minor,name,init)

A handy macro to define a plugin description. This macro handles with all the issues involved with the different linking methods for this plugin.

`major` : | The major version of GStreamer this plugin was compiled against.
`minor` : | The minor version of GStreamer this plugin was compiled against.
`name` : | The name of the plugin.
`init` : | The init function of this plugin.

### GST_PLUGIN_DESC_DYNAMIC()

    #define     GST_PLUGIN_DESC_DYNAMIC(major,minor,name,init)

The macro used to define dynamically loaded plugins.

`major` : | The major version of GStreamer this plugin was compiled against.
`minor` : | The minor version of GStreamer this plugin was compiled against.
`name` : | The name of the plugin.
`init` : | The init function of this plugin.

### GST_PLUGIN_DESC_STATIC()

    #define     GST_PLUGIN_DESC_STATIC(major,minor,name,init)

A macro used to define a statically linked plugin.

`major` : | The major version of GStreamer this plugin was compiled against.
`minor` : | The minor version of GStreamer this plugin was compiled against.
`name` : | The name of the plugin.
`init` : | The init function of this plugin.

### gst_plugin_new ()

    GstPlugin*  gst_plugin_new                  (const gchar *filename);

Creates a plugin from the given filename

`filename` : | The filename of the plugin
Returns : | A new GstPlugin object

### gst_plugin_set_name ()

    void        gst_plugin_set_name             (GstPlugin *plugin,
                                                 const gchar *name);

Sets the name (should be short) of the plugin.

`plugin` : | plugin to set name of
`name` : | new name

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

    const gchar* gst_plugin_get_longname        (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_set_longname ()

    void        gst_plugin_set_longname         (GstPlugin *plugin,
                                                 const gchar *longname);

Sets the long name (should be descriptive) of the plugin.

`plugin` : | plugin to set long name of
`longname` : | new long name

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

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

    gboolean    gst_plugin_load_plugin          (GstPlugin *plugin,
                                                 GError **error);

Load the given plugin.

`plugin` : | The plugin to load
`error` : | Pointer to a NULL-valued GError.
Returns : | whether or not the plugin loaded. Sets `error` as appropriate.

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