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

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. This version allows user data to be passed to init function (useful for bindings).

plugin : The plugin object that can be used to register GstPluginFeatures for this plugin.
user_data : The user 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.

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 rebuild.

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 rebuild.

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,
                                                         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,
                                                         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 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
Generated by GTK-Doc V1.10