![]() |
![]() |
![]() |
GStreamer 0.10 Core Reference Manual | ![]() |
---|---|---|---|---|
#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);
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.
GQuark gst_plugin_error_quark (void);
Get the error quark.
Returns : | The error quark used in GError messages |
#define GST_PLUGIN_ERROR gst_plugin_error_quark ()
The error message category quark
typedef enum { GST_PLUGIN_ERROR_MODULE, GST_PLUGIN_ERROR_DEPENDENCIES, GST_PLUGIN_ERROR_NAME_MISMATCH } GstPluginError;
The plugin loading errors
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 |
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
|
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
#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) |
#define GST_PLUGIN_DEFINE_STATIC(major,minor,name,description,init,version,license,package,origin)
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) |
#define GST_LICENSE_UNKNOWN "unknown"
To be used in GST_PLUGIN_DEFINE or GST_PLUGIN_DEFINE_STATIC if usure about the licence.
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 |
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 |
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 |
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 |
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 |
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 |
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 |
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 |
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 |
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. |
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 |
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
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
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. |
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. |
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. |
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. |
void gst_plugin_list_free (GList *list);
Unrefs each member of list
, then frees the list.
list : |
list of GstPlugin |
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
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
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()
.
Since 0.10.22
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
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