Next: , Previous: GstQuery, Up: Top

31 GstRegistry

Abstract base class for management of objects

31.1 Overview

One registry holds the metadata of a set of plugins. All registries build the <gst-registry-pool>.

Design:

The <gst-registry> object is a list of plugins and some functions for dealing with them. <gst-plugins> are matched 1-1 with a file on disk, and may or may not be loaded at a given time. There may be multiple <gst-registry> objects, but the "default registry" is the only object that has any meaning to the core.

The registry.xml file is actually a cache of plugin information. This is unlike versions prior to 0.10, where the registry file was the primary source of plugin information, and was created by the gst-register command.

The primary source, at all times, of plugin information is each plugin file itself. Thus, if an application wants information about a particular plugin, or wants to search for a feature that satisfies given criteria, the primary means of doing so is to load every plugin and look at the resulting information that is gathered in the default registry. Clearly, this is a time consuming process, so we cache information in the registry.xml file.

On startup, plugins are searched for in the plugin search path. This path can be set directly using the ‘GST_PLUGIN_PATH’ environment variable. The registry file is loaded from ~/.gstreamer-$GST_MAJORMINOR/registry-$ARCH.xml or the file listed in the ‘GST_REGISTRY’ env var. The only reason to change the registry location is for testing.

For each plugin that is found in the plugin search path, there could be 3 possibilities for cached information:

In the first two cases, the plugin is loaded and the cache updated. In addition to these cases, the cache may have entries for plugins that are not relevant to the current process. These are marked as not available to the current process. If the cache is updated for whatever reason, it is marked dirty.

A dirty cache is written out at the end of initialization. Each entry is checked to make sure the information is minimally valid. If not, the entry is simply dropped.

Implementation notes:

The "cache" and "default registry" are different concepts and can represent different sets of plugins. For various reasons, at init time, the cache is stored in the default registry, and plugins not relevant to the current process are marked with the ‘GST_PLUGIN_FLAG_CACHED’ bit. These plugins are removed at the end of intitialization.

31.2 Usage

— Class: <gst-registry>

This <gobject> class defines no properties, other than those defined by its superclasses.

— Signal on <gst-registry>: plugin-added (arg0 <gpointer>)

Signals that a plugin has been added to the registry (possibly replacing a previously-added one by the same name)

— Signal on <gst-registry>: feature-added (arg0 <gpointer>)

Signals that a feature has been added to the registry (possibly replacing a previously-added one by the same name)

— Function: gst-registry-get-default   (ret <gst-registry>)

Retrieves the default registry. The caller does not own a reference on the registry, as it is alive as long as GStreamer is initialized.

ret
The default <gst-registry>.
— Function: gst-registry-get-feature-list (self <gst-registry>) (type <gtype>)   (ret glist-of)
— Method: get-feature-list

Retrieves a <g-list> of <gst-plugin-feature> of type.

registry
a <gst-registry>
type
a <g-type>.
ret
a <g-list> of <gst-plugin-feature> of type. gst_plugin_feature_list_free after usage. MT safe.
— Function: gst-registry-get-path-list (self <gst-registry>)   (ret glist-of)
— Method: get-path-list

Get the list of paths for the given registry.

registry
the registry to get the pathlist of
ret
A Glist of paths as strings. g_list_free after use. MT safe.
— Function: gst-registry-get-plugin-list (self <gst-registry>)   (ret glist-of)
— Method: get-plugin-list

Get a copy of all plugins registered in the given registry. The refcount of each element in the list in incremented.

registry
the registry to search
ret
a <g-list> of <gst-plugin>. gst_plugin_list_free after use. MT safe.
— Function: gst-registry-add-plugin (self <gst-registry>) (plugin <gst-plugin>)   (ret bool)
— Method: add-plugin

Add the plugin to the registry. The plugin-added signal will be emitted. This function will sink plugin.

registry
the registry to add the plugin to
plugin
the plugin to add
ret
TRUE on success. MT safe.
— Function: gst-registry-remove-plugin (self <gst-registry>) (plugin <gst-plugin>)
— Method: remove-plugin

Remove the plugin from the registry.

MT safe.

registry
the registry to remove the plugin from
plugin
the plugin to remove
— Function: gst-registry-plugin-filter (self <gst-registry>) (filter <gst-plugin-filter>) (first bool) (user_data <gpointer>)   (ret glist-of)
— Method: plugin-filter

Runs a filter against all plugins in the registry and returns a <g-list> with the results. If the first flag is set, only the first match is returned (as a list with a single object). Every plugin is reffed; use gst-plugin-list-free after use, which will unref again.

registry
registry to query
filter
the filter to use
first
only return first match
user-data
user data passed to the filter function
ret
a <g-list> of <gst-plugin>. Use gst-plugin-list-free after usage. MT safe.
— Function: gst-registry-feature-filter (self <gst-registry>) (filter <gst-plugin-feature-filter>) (first bool) (user_data <gpointer>)   (ret glist-of)
— Method: feature-filter

Runs a filter against all features of the plugins in the registry and returns a GList with the results. If the first flag is set, only the first match is returned (as a list with a single object).

registry
registry to query
filter
the filter to use
first
only return first match
user-data
user data passed to the filter function
ret
a GList of plugin features, gst_plugin_feature_list_free after use. MT safe.
— Function: gst-registry-find-plugin (self <gst-registry>) (name mchars)   (ret <gst-plugin>)
— Method: find-plugin

Find the plugin with the given name in the registry. The plugin will be reffed; caller is responsible for unreffing.

registry
the registry to search
name
the plugin name to find
ret
The plugin with the given name or NULL if the plugin was not found. gst-object-unref after usage. MT safe.
— Function: gst-registry-find-feature (self <gst-registry>) (name mchars) (type <gtype>)   (ret <gst-plugin-feature>)
— Method: find-feature

Find the pluginfeature with the given name and type in the registry.

registry
the registry to search
name
the pluginfeature name to find
type
the pluginfeature type to find
ret
The pluginfeature with the given name and type or NULL if the plugin was not found. gst-object-unref after usage. MT safe.
— Function: gst-registry-lookup-feature (self <gst-registry>) (name mchars)   (ret <gst-plugin-feature>)
— Method: lookup-feature

Find a <gst-plugin-feature> with name in registry.

registry
a <gst-registry>
name
a <gst-plugin-feature> name
ret
a <gst-plugin-feature> with its refcount incremented, use gst-object-unref after usage. MT safe.
— Function: gst-registry-scan-path (self <gst-registry>) (path mchars)   (ret bool)
— Method: scan-path

Add the given path to the registry. The syntax of the path is specific to the registry. If the path has already been added, do nothing.

registry
the registry to add the path to
path
the path to add to the registry
ret
‘#t’ if registry changed
— Function: gst-registry-xml-read-cache (self <gst-registry>) (location mchars)   (ret bool)
— Method: xml-read-cache

Read the contents of the XML cache file at location into registry.

registry
a <gst-registry>
location
a filename
ret
‘#t’ on success.
— Function: gst-registry-xml-write-cache (self <gst-registry>) (location mchars)   (ret bool)
— Method: xml-write-cache

Write registry in an XML format at the location given by location. Directories are automatically created.

registry
a <gst-registry>
location
a filename
ret
TRUE on success.
— Function: gst-registry-lookup (self <gst-registry>) (filename mchars)   (ret <gst-plugin>)
— Method: lookup

Look up a plugin in the given registry with the given filename. If found, plugin is reffed.

registry
the registry to look up in
filename
the name of the file to look up
ret
the <gst-plugin> if found, or NULL if not. gst-object-unref after usage.
— Function: gst-registry-remove-feature (self <gst-registry>) (feature <gst-plugin-feature>)
— Method: remove-feature

Remove the feature from the registry.

MT safe.

registry
the registry to remove the feature from
feature
the feature to remove
— Function: gst-registry-add-feature (self <gst-registry>) (feature <gst-plugin-feature>)   (ret bool)
— Method: add-feature

Add the feature to the registry. The feature-added signal will be emitted. This function sinks feature.

registry
the registry to add the plugin to
feature
the feature to add
ret
TRUE on success. MT safe.