GstPlugin

GstPlugin — Container for features loaded from a shared object module

Functions

Types and Values

Object Hierarchy

    GObject
    ╰── GInitiallyUnowned
        ╰── GstObject
            ╰── GstPlugin

Includes

#include <gst/gst.h>

Description

GStreamer is extensible, so GstElement instances can be loaded at runtime. A plugin system can provide one or more of the basic

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

Functions

gst_plugin_error_quark ()

GQuark
gst_plugin_error_quark (void);

Get the error quark.

Returns

The error quark used in GError messages


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.

Parameters

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

Parameters

plugin

The plugin object

 

user_data

extra data

 

Returns

TRUE if plugin initialised successfully


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.

Parameters

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)

 

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.

Parameters

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

Parameters

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

Parameters

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

Parameters

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

Parameters

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.

Parameters

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

Parameters

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.

Parameters

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

Parameters

plugin

plugin to get the version of

 

Returns

the version of the plugin


gst_plugin_get_release_date_string ()

const gchar *
gst_plugin_get_release_date_string (GstPlugin *plugin);

Get the release date (and possibly time) in form of a string, if available.

For normal GStreamer plugin releases this will usually just be a date in the form of "YYYY-MM-DD", while pre-releases and builds from git may contain a time component after the date as well, in which case the string will be formatted like "YYYY-MM-DDTHH:MMZ" (e.g. "2012-04-30T09:30Z").

There may be plugins that do not have a valid release date set on them.

Parameters

plugin

plugin to get the release date of

 

Returns

the date string of the plugin, or NULL if not available.


gst_plugin_is_loaded ()

gboolean
gst_plugin_is_loaded (GstPlugin *plugin);

queries if the plugin is loaded into memory

Parameters

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.

Parameters

plugin

a plugin

 

Returns

The cached data as a GstStructure or NULL.

[transfer none]


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.

Parameters

plugin

a plugin

 

cache_data

a structure containing the data to cache.

[transfer full]

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.

Parameters

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.

[transfer full]


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;

Parameters

plugin

plugin to load.

[transfer none]

Returns

a reference to a loaded plugin, or NULL on error.

[transfer full]


gst_plugin_load_by_name ()

GstPlugin *
gst_plugin_load_by_name (const gchar *name);

Load the named plugin. Refs the plugin.

Parameters

name

name of plugin to load

 

Returns

a reference to a loaded plugin, or NULL on error.

[transfer full]


gst_plugin_list_free ()

void
gst_plugin_list_free (GList *list);

Unrefs each member of list , then frees the list.

Parameters

list

list of GstPlugin.

[transfer full][element-type Gst.Plugin]

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.

Parameters

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.

[scope call]

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.


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.

Parameters

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.

[scope call]

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.


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.

Parameters

plugin

a GstPlugin

 

env_vars

NULL-terminated array of environment 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".

[allow-none]

paths

NULL-terminated array of directories/paths where dependent files may be, or NULL.

[allow-none]

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.

[allow-none]

flags

optional flags, or GST_PLUGIN_DEPENDENCY_FLAG_NONE

 

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

Parameters

plugin

the GstPlugin

 

env_vars

one or more environment 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".

[allow-none]

paths

one ore more directory paths (separated by ':' or ';' or ','), or NULL. Example: "/usr/lib/mystuff/plugins".

[allow-none]

names

one or more file names or file name suffixes (separated by commas), or NULL.

[allow-none]

flags

optional flags, or GST_PLUGIN_DEPENDENCY_FLAG_NONE

 

Types and Values

GST_PLUGIN_ERROR

#define GST_PLUGIN_ERROR gst_plugin_error_quark ()

The error message category quark


enum GstPluginError

The plugin loading errors

Members

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 opaque plugin object


struct GstPluginDesc

struct GstPluginDesc {
  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;
};

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.

Members

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.

 

GST_LICENSE_UNKNOWN

#define GST_LICENSE_UNKNOWN "unknown"

To be used in GST_PLUGIN_DEFINE if usure about the licence.


enum GstPluginFlags

The plugin loading state

Members

GST_PLUGIN_FLAG_CACHED

Temporarily loaded plugins

 

GST_PLUGIN_FLAG_BLACKLISTED

The plugin won't be scanned (again)

 

enum GstPluginDependencyFlags

Flags used in connection with gst_plugin_add_dependency().

Members

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

 

See Also

GstPluginFeature, GstElementFactory