1/* gstreamermm - a C++ wrapper for gstreamer
2 *
3 * Copyright 2008 The gstreamermm Development Team
4 *
5 * This library is free software; you can redistribute it and/or
6 * modify it under the terms of the GNU Lesser General Public
7 * License as published by the Free Software Foundation; either
8 * version 2.1 of the License, or (at your option) any later version.
9 *
10 * This library is distributed in the hope that it will be useful,
11 * but WITHOUT ANY WARRANTY; without even the implied warranty of
12 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
13 * Lesser General Public License for more details.
14 *
15 * You should have received a copy of the GNU Lesser General Public
16 * License along with this library; if not, write to the Free
17 * Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
18 */
19
20#include <gst/gst.h>
21#include <gstreamermm/object.h>
22#include <gstreamermm/plugin.h>
23#include <gstreamermm/pluginfeature.h>
24
25_DEFS(gstreamermm,gst)
26
27namespace Gst
28{
29
30class Plugin;
31class PluginFeature;
32
33/** An abstract base class for management of Gst::Plugin objects.
34 * One registry holds the metadata of a set of plugins.
35 *
36 * Design:
37 *
38 * The Gst::Registry object is a list of plugins and some functions for dealing
39 * with them. Each Gst::Plugin is matched 1-1 with a file on disk, and may or
40 * may not be loaded at a given time.
41 *
42 * The primary source, at all times, of plugin information is each plugin file
43 * itself. Thus, if an application wants information about a particular plugin,
44 * or wants to search for a feature that satisfies given criteria, the primary
45 * means of doing so is to load every plugin and look at the resulting
46 * information that is gathered in the default registry. Clearly, this is a
47 * time consuming process, so we cache information in the registry file. The
48 * format and location of the cache file is internal to gstreamer.
49 *
50 * On startup, plugins are searched for in the plugin search path. The
51 * following locations are checked in this order:
52 *
53 *  - location from --gst-plugin-path commandline option.
54 *  - the GST_PLUGIN_PATH environment variable.
55 *  - the GST_PLUGIN_SYSTEM_PATH environment variable.
56 *  - default locations (if GST_PLUGIN_SYSTEM_PATH is not set). Those default
57 *    locations are: ~/.gstreamer-$GST_API_VERSION/plugins/ and
58 *    $prefix/libs/gstreamer-$GST_API_VERSION/.
59 *
60 * The registry cache file is loaded from
61 * ~/.gstreamer-$GST_API_VERSION/registry-$ARCH.bin or the file listed in the
62 * GST_REGISTRY env var. One reason to change the registry location is for
63 * testing.
64 *
65 * For each plugin that is found in the plugin search path, there could be 3
66 * possibilities for cached information:
67 *
68 *  - the cache may not contain information about a given file.
69 *  - the cache may have stale information.
70 *  - the cache may have current information.
71 *
72 * In the first two cases, the plugin is loaded and the cache updated. In
73 * addition to these cases, the cache may have entries for plugins that are not
74 * relevant to the current process. These are marked as not available to the
75 * current process. If the cache is updated for whatever reason, it is marked
76 * dirty.
77 *
78 * A dirty cache is written out at the end of initialization. Each entry is
79 * checked to make sure the information is minimally valid. If not, the entry
80 * is simply dropped.
81 *
82 * Implementation notes:
83 *
84 * The "cache" and "registry" are different concepts and can represent
85 * different sets of plugins. For various reasons, at init time, the cache is
86 * stored in the default registry, and plugins not relevant to the current
87 * process are marked with the GST_PLUGIN_FLAG_CACHED bit. These plugins are
88 * removed at the end of initialization.
89 *
90 * Last reviewed on 2012-03-29 (0.11.3)
91 */
92class Registry : public Object
93{
94  _CLASS_GOBJECT(Registry, GstRegistry, GST_REGISTRY, Gst::Object, GstObject)
95
96public:
97#m4 _CONVERSION(`GList*',`Glib::ListHandle< Glib::RefPtr<Gst::PluginFeature> >',`$2($3, Glib::OWNERSHIP_DEEP)')
98  _WRAP_METHOD(Glib::ListHandle< Glib::RefPtr<Gst::PluginFeature> > get_feature_list(GType type), gst_registry_get_feature_list)
99
100#m4 _CONVERSION(`GList*',`Glib::ListHandle< Glib::RefPtr<const Gst::PluginFeature> >',`$2($3, Glib::OWNERSHIP_DEEP)')
101  _WRAP_METHOD(Glib::ListHandle< Glib::RefPtr<const Gst::PluginFeature> > get_feature_list(GType type) const, gst_registry_get_feature_list)
102
103  _WRAP_METHOD(guint32 get_feature_list_cookie() const, gst_registry_get_feature_list_cookie)
104  _WRAP_METHOD(Glib::ListHandle< Glib::RefPtr<Gst::PluginFeature> > get_feature_list(const Glib::ustring& name), gst_registry_get_feature_list_by_plugin)
105  _WRAP_METHOD(Glib::ListHandle< Glib::RefPtr<const Gst::PluginFeature> > get_feature_list(const Glib::ustring& name) const, gst_registry_get_feature_list_by_plugin)
106
107#m4 _CONVERSION(`GList*',`Glib::ListHandle< Glib::RefPtr<Gst::Plugin> >',`$2($3, Glib::OWNERSHIP_DEEP)')
108  _WRAP_METHOD(Glib::ListHandle< Glib::RefPtr<Gst::Plugin> > get_plugin_list(), gst_registry_get_plugin_list)
109
110#m4 _CONVERSION(`GList*',`Glib::ListHandle< Glib::RefPtr<const Gst::Plugin> >',`$2($3, Glib::OWNERSHIP_DEEP)')
111  _WRAP_METHOD(Glib::ListHandle< Glib::RefPtr<const Gst::Plugin> > get_plugin_list() const, gst_registry_get_plugin_list)
112
113  _WRAP_METHOD(void remove_plugin(const Glib::RefPtr<Gst::Plugin>& plugin), gst_registry_remove_plugin)
114
115  _WRAP_METHOD(bool add_plugin(Glib::RefPtr<Gst::Plugin>&& plugin), gst_registry_add_plugin)
116
117  /// A add_plugin() convenience overload. Allows to re-use @a plugin parameter after function call.
118  void add_plugin(const Glib::RefPtr<Gst::Plugin>& plugin);
119  /** Runs a filter against all plugins in the registry and returns a List with
120   * the results. If the first flag is set, only the first match is returned
121   * (as a list with a single object).
122   *
123   * @param filter The filter to use.
124   * @param first Only return first match.
125   * @return A list of Gst::Plugin. MT safe.
126   *
127   */
128  Glib::ListHandle< Glib::RefPtr<Gst::Plugin> > get_plugin_list(const Plugin::SlotFilter& filter, bool first);
129  _IGNORE(gst_registry_plugin_filter)
130
131  /** Runs a filter against all plugins in the registry and returns a List with
132   * the results. If the first flag is set, only the first match is returned
133   * (as a list with a single object).
134   *
135   * @param filter The filter to use.
136   * @param first Only return first match.
137   * @return A list of Gst::Plugin. MT safe.
138   *
139   */
140  Glib::ListHandle< Glib::RefPtr<const Gst::Plugin> > get_plugin_list(const Plugin::SlotFilter& filter, bool first) const;
141
142  /** Runs a filter against all features of the plugins in the registry and
143   * returns a List with the results. If the first flag is set, only the first
144   * match is returned (as a list with a single object).
145   *
146   * @param filter The filter to use.
147   * @param first Only return first match.
148   * @return A list of Gst::PluginFeature. MT safe.
149   */
150  Glib::ListHandle< Glib::RefPtr<Gst::PluginFeature> > get_feature_list(const PluginFeature::SlotFilter& filter, bool first);
151  _IGNORE(gst_registry_feature_filter)
152
153  /** Runs a filter against all features of the plugins in the registry and
154   * returns a List with the results. If the first flag is set, only the first
155   * match is returned (as a list with a single object).
156   *
157   * @param filter The filter to use.
158   * @param first Only return first match.
159   * @return A list of Gst::PluginFeature. MT safe.
160   */
161  Glib::ListHandle< Glib::RefPtr<const Gst::PluginFeature> > get_feature_list(const PluginFeature::SlotFilter& filter, bool first) const;
162
163  _WRAP_METHOD(Glib::RefPtr<Gst::Plugin> find_plugin(const Glib::ustring& name), gst_registry_find_plugin)
164  _WRAP_METHOD(Glib::RefPtr<const Gst::Plugin> find_plugin(const Glib::ustring& name) const, gst_registry_find_plugin, constversion)
165  _WRAP_METHOD(Glib::RefPtr<Gst::PluginFeature> find_feature(const Glib::ustring& name, GType type), gst_registry_find_feature)
166  _WRAP_METHOD(Glib::RefPtr<const Gst::PluginFeature> find_feature(const Glib::ustring& name, GType type) const, gst_registry_find_feature, constversion)
167  _WRAP_METHOD(Glib::RefPtr<Gst::PluginFeature> lookup_feature(const Glib::ustring& name), gst_registry_lookup_feature)
168  _WRAP_METHOD(Glib::RefPtr<const Gst::PluginFeature> lookup_feature(const Glib::ustring& name) const, gst_registry_lookup_feature, constversion)
169  _WRAP_METHOD(bool scan_path(const Glib::ustring& path), gst_registry_scan_path)
170
171  _WRAP_METHOD(Glib::RefPtr<Gst::Plugin> lookup(const Glib::ustring& filename), gst_registry_lookup)
172  _WRAP_METHOD(Glib::RefPtr<const Gst::Plugin> lookup(const Glib::ustring& filename) const, gst_registry_lookup, constversion)
173  _WRAP_METHOD(void remove_feature(const Glib::RefPtr<Gst::PluginFeature>& feature), gst_registry_remove_feature)
174  _WRAP_METHOD(void add_feature(Glib::RefPtr<Gst::PluginFeature>&& feature), gst_registry_add_feature)
175  _WRAP_METHOD(bool check_feature_version(const Glib::ustring& feature_name, guint min_major, guint min_minor, guint min_micro), gst_registry_check_feature_version)
176
177  /// This methods appear in .defs file, because they are removed from API using #if 0 directive.
178  /// h2def.py script can't detect that case, so methods have to be ignored manually.
179  _IGNORE(gst_registry_add_path, gst_registry_get_path_list)
180
181  /// A add_feature() convenience overload. Allows to re-use @a feature parameter after function call.
182  void add_feature(const Glib::RefPtr<Gst::PluginFeature>& feature);
183
184  static Glib::RefPtr<Gst::Registry> get();
185};
186
187} // namespace Gst
188