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;
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);
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);
G_CONST_RETURN gchar* gst_plugin_get_version
                                            (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 (e.g. from the GstRegistryPool), 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`	The plugin has already be loaded from a different file

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 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 major version number of core that plugin was compiled for
gint `minor_version`	the minor version number of core that plugin was compiled for
gchar *`name`	a unique name of the plugin
gchar *`description`
GstPluginInitFunc `plugin_init`	The init function of this plugin.
GstPluginExitFunc `plugin_exit`
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]

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);

Exiting function when plugin is unloaded.

plugin : The plugin object that can be used to unregister stuff for this plugin.

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

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

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.

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

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

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

G_CONST_RETURN 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_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". (exception to this rule is 'riff', which .so name is 'gstriff')

`name` :	name of library to load
Returns :	whether the library was loaded or not (and returns TRUE if it was already loaded)