1 /*
2  * This file is part of gtkD.
3  *
4  * gtkD is free software; you can redistribute it and/or modify
5  * it under the terms of the GNU Lesser General Public License
6  * as published by the Free Software Foundation; either version 3
7  * of the License, or (at your option) any later version, with
8  * some exceptions, please read the COPYING file.
9  *
10  * gtkD 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
13  * GNU Lesser General Public License for more details.
14  *
15  * You should have received a copy of the GNU Lesser General Public License
16  * along with gtkD; if not, write to the Free Software
17  * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110, USA
18  */
19 
20 // generated automatically - do not change
21 // find conversion definition on APILookup.txt
22 // implement new conversion functionalities on the wrap.utils pakage
23 
24 
25 module gstreamer.Registry;
26 
27 private import glib.ListG;
28 private import glib.Str;
29 private import gobject.ObjectG;
30 private import gobject.Signals;
31 private import gstreamer.ObjectGst;
32 private import gstreamer.Plugin;
33 private import gstreamer.PluginFeature;
34 private import gstreamerc.gstreamer;
35 public  import gstreamerc.gstreamertypes;
36 public  import gtkc.gdktypes;
37 
38 
39 /**
40  * One registry holds the metadata of a set of plugins.
41  * 
42  * <emphasis role="bold">Design:</emphasis>
43  * 
44  * The #GstRegistry object is a list of plugins and some functions for dealing
45  * with them. Each #GstPlugin is matched 1-1 with a file on disk, and may or may
46  * not be loaded at a given time.
47  * 
48  * The primary source, at all times, of plugin information is each plugin file
49  * itself. Thus, if an application wants information about a particular plugin,
50  * or wants to search for a feature that satisfies given criteria, the primary
51  * means of doing so is to load every plugin and look at the resulting
52  * information that is gathered in the default registry. Clearly, this is a time
53  * consuming process, so we cache information in the registry file. The format
54  * and location of the cache file is internal to gstreamer.
55  * 
56  * On startup, plugins are searched for in the plugin search path. The following
57  * locations are checked in this order:
58  * <itemizedlist>
59  * <listitem>
60  * <para>location from --gst-plugin-path commandline option.</para>
61  * </listitem>
62  * <listitem>
63  * <para>the GST_PLUGIN_PATH environment variable.</para>
64  * </listitem>
65  * <listitem>
66  * <para>the GST_PLUGIN_SYSTEM_PATH environment variable.</para>
67  * </listitem>
68  * <listitem>
69  * <para>default locations (if GST_PLUGIN_SYSTEM_PATH is not set). Those
70  * default locations are:
71  * <filename>$XDG_DATA_HOME/gstreamer-$GST_API_VERSION/plugins/</filename>
72  * and <filename>$prefix/libs/gstreamer-$GST_API_VERSION/</filename>.
73  * <ulink url="http://standards.freedesktop.org/basedir-spec/basedir-spec-latest.html">
74  * <filename>$XDG_DATA_HOME</filename></ulink> defaults to
75  * <filename>$HOME/.local/share</filename>.
76  * </para>
77  * </listitem>
78  * </itemizedlist>
79  * The registry cache file is loaded from
80  * <filename>$XDG_CACHE_HOME/gstreamer-$GST_API_VERSION/registry-$ARCH.bin</filename>
81  * (where
82  * <ulink url="http://standards.freedesktop.org/basedir-spec/basedir-spec-latest.html">
83  * <filename>$XDG_CACHE_HOME</filename></ulink> defaults to
84  * <filename>$HOME/.cache</filename>) or the file listed in the GST_REGISTRY
85  * env var. One reason to change the registry location is for testing.
86  * 
87  * For each plugin that is found in the plugin search path, there could be 3
88  * possibilities for cached information:
89  * <itemizedlist>
90  * <listitem>
91  * <para>the cache may not contain information about a given file.</para>
92  * </listitem>
93  * <listitem>
94  * <para>the cache may have stale information.</para>
95  * </listitem>
96  * <listitem>
97  * <para>the cache may have current information.</para>
98  * </listitem>
99  * </itemizedlist>
100  * 
101  * In the first two cases, the plugin is loaded and the cache updated. In
102  * addition to these cases, the cache may have entries for plugins that are not
103  * relevant to the current process. These are marked as not available to the
104  * current process. If the cache is updated for whatever reason, it is marked
105  * dirty.
106  * 
107  * A dirty cache is written out at the end of initialization. Each entry is
108  * checked to make sure the information is minimally valid. If not, the entry is
109  * simply dropped.
110  * 
111  * <emphasis role="bold">Implementation notes:</emphasis>
112  * 
113  * The "cache" and "registry" are different concepts and can represent
114  * different sets of plugins. For various reasons, at init time, the cache is
115  * stored in the default registry, and plugins not relevant to the current
116  * process are marked with the %GST_PLUGIN_FLAG_CACHED bit. These plugins are
117  * removed at the end of initialization.
118  */
119 public class Registry : ObjectGst
120 {
121 	/** the main Gtk struct */
122 	protected GstRegistry* gstRegistry;
123 
124 	/** Get the main Gtk struct */
125 	public GstRegistry* getRegistryStruct()
126 	{
127 		return gstRegistry;
128 	}
129 
130 	/** the main Gtk struct as a void* */
131 	protected override void* getStruct()
132 	{
133 		return cast(void*)gstRegistry;
134 	}
135 
136 	protected override void setStruct(GObject* obj)
137 	{
138 		gstRegistry = cast(GstRegistry*)obj;
139 		super.setStruct(obj);
140 	}
141 
142 	/**
143 	 * Sets our main struct and passes it to the parent class.
144 	 */
145 	public this (GstRegistry* gstRegistry, bool ownedRef = false)
146 	{
147 		this.gstRegistry = gstRegistry;
148 		super(cast(GstObject*)gstRegistry, ownedRef);
149 	}
150 
151 	/**
152 	 */
153 
154 	public static GType getType()
155 	{
156 		return gst_registry_get_type();
157 	}
158 
159 	/**
160 	 * By default GStreamer will perform scanning and rebuilding of the
161 	 * registry file using a helper child process.
162 	 *
163 	 * Applications might want to disable this behaviour with the
164 	 * gst_registry_fork_set_enabled() function, in which case new plugins
165 	 * are scanned (and loaded) into the application process.
166 	 *
167 	 * Return: %TRUE if GStreamer will use the child helper process when
168 	 *     rebuilding the registry.
169 	 */
170 	public static bool forkIsEnabled()
171 	{
172 		return gst_registry_fork_is_enabled() != 0;
173 	}
174 
175 	/**
176 	 * Applications might want to disable/enable spawning of a child helper process
177 	 * when rebuilding the registry. See gst_registry_fork_is_enabled() for more
178 	 * information.
179 	 *
180 	 * Params:
181 	 *     enabled = whether rebuilding the registry can use a temporary child helper process.
182 	 */
183 	public static void forkSetEnabled(bool enabled)
184 	{
185 		gst_registry_fork_set_enabled(enabled);
186 	}
187 
188 	/**
189 	 * Retrieves the singleton plugin registry. The caller does not own a
190 	 * reference on the registry, as it is alive as long as GStreamer is
191 	 * initialized.
192 	 *
193 	 * Return: the #GstRegistry.
194 	 */
195 	public static Registry get()
196 	{
197 		auto p = gst_registry_get();
198 		
199 		if(p is null)
200 		{
201 			return null;
202 		}
203 		
204 		return ObjectG.getDObject!(Registry)(cast(GstRegistry*) p);
205 	}
206 
207 	/**
208 	 * Add the feature to the registry. The feature-added signal will be emitted.
209 	 * This function sinks @feature.
210 	 *
211 	 * Params:
212 	 *     feature = the feature to add
213 	 *
214 	 * Return: %TRUE on success.
215 	 *
216 	 *     MT safe.
217 	 */
218 	public bool addFeature(PluginFeature feature)
219 	{
220 		return gst_registry_add_feature(gstRegistry, (feature is null) ? null : feature.getPluginFeatureStruct()) != 0;
221 	}
222 
223 	/**
224 	 * Add the plugin to the registry. The plugin-added signal will be emitted.
225 	 * This function will sink @plugin.
226 	 *
227 	 * Params:
228 	 *     plugin = the plugin to add
229 	 *
230 	 * Return: %TRUE on success.
231 	 *
232 	 *     MT safe.
233 	 */
234 	public bool addPlugin(Plugin plugin)
235 	{
236 		return gst_registry_add_plugin(gstRegistry, (plugin is null) ? null : plugin.getPluginStruct()) != 0;
237 	}
238 
239 	/**
240 	 * Checks whether a plugin feature by the given name exists in
241 	 * @registry and whether its version is at least the
242 	 * version required.
243 	 *
244 	 * Params:
245 	 *     featureName = the name of the feature (e.g. "oggdemux")
246 	 *     minMajor = the minimum major version number
247 	 *     minMinor = the minimum minor version number
248 	 *     minMicro = the minimum micro version number
249 	 *
250 	 * Return: %TRUE if the feature could be found and the version is
251 	 *     the same as the required version or newer, and %FALSE otherwise.
252 	 */
253 	public bool checkFeatureVersion(string featureName, uint minMajor, uint minMinor, uint minMicro)
254 	{
255 		return gst_registry_check_feature_version(gstRegistry, Str.toStringz(featureName), minMajor, minMinor, minMicro) != 0;
256 	}
257 
258 	/**
259 	 * Runs a filter against all features of the plugins in the registry
260 	 * and returns a GList with the results.
261 	 * If the first flag is set, only the first match is
262 	 * returned (as a list with a single object).
263 	 *
264 	 * Params:
265 	 *     filter = the filter to use
266 	 *     first = only return first match
267 	 *     userData = user data passed to the filter function
268 	 *
269 	 * Return: a #GList of
270 	 *     #GstPluginFeature. Use gst_plugin_feature_list_free() after usage.
271 	 *
272 	 *     MT safe.
273 	 */
274 	public ListG featureFilter(GstPluginFeatureFilter filter, bool first, void* userData)
275 	{
276 		auto p = gst_registry_feature_filter(gstRegistry, filter, first, userData);
277 		
278 		if(p is null)
279 		{
280 			return null;
281 		}
282 		
283 		return new ListG(cast(GList*) p);
284 	}
285 
286 	/**
287 	 * Find the pluginfeature with the given name and type in the registry.
288 	 *
289 	 * Params:
290 	 *     name = the pluginfeature name to find
291 	 *     type = the pluginfeature type to find
292 	 *
293 	 * Return: the pluginfeature with the
294 	 *     given name and type or %NULL if the plugin was not
295 	 *     found. gst_object_unref() after usage.
296 	 *
297 	 *     MT safe.
298 	 */
299 	public PluginFeature findFeature(string name, GType type)
300 	{
301 		auto p = gst_registry_find_feature(gstRegistry, Str.toStringz(name), type);
302 		
303 		if(p is null)
304 		{
305 			return null;
306 		}
307 		
308 		return ObjectG.getDObject!(PluginFeature)(cast(GstPluginFeature*) p, true);
309 	}
310 
311 	/**
312 	 * Find the plugin with the given name in the registry.
313 	 * The plugin will be reffed; caller is responsible for unreffing.
314 	 *
315 	 * Params:
316 	 *     name = the plugin name to find
317 	 *
318 	 * Return: the plugin with the given name
319 	 *     or %NULL if the plugin was not found. gst_object_unref() after
320 	 *     usage.
321 	 *
322 	 *     MT safe.
323 	 */
324 	public Plugin findPlugin(string name)
325 	{
326 		auto p = gst_registry_find_plugin(gstRegistry, Str.toStringz(name));
327 		
328 		if(p is null)
329 		{
330 			return null;
331 		}
332 		
333 		return ObjectG.getDObject!(Plugin)(cast(GstPlugin*) p, true);
334 	}
335 
336 	/**
337 	 * Retrieves a #GList of #GstPluginFeature of @type.
338 	 *
339 	 * Params:
340 	 *     type = a #GType.
341 	 *
342 	 * Return: a #GList of
343 	 *     #GstPluginFeature of @type. Use gst_plugin_feature_list_free() after use
344 	 *
345 	 *     MT safe.
346 	 */
347 	public ListG getFeatureList(GType type)
348 	{
349 		auto p = gst_registry_get_feature_list(gstRegistry, type);
350 		
351 		if(p is null)
352 		{
353 			return null;
354 		}
355 		
356 		return new ListG(cast(GList*) p);
357 	}
358 
359 	/**
360 	 * Retrieves a #GList of features of the plugin with name @name.
361 	 *
362 	 * Params:
363 	 *     name = a plugin name.
364 	 *
365 	 * Return: a #GList of
366 	 *     #GstPluginFeature. Use gst_plugin_feature_list_free() after usage.
367 	 */
368 	public ListG getFeatureListByPlugin(string name)
369 	{
370 		auto p = gst_registry_get_feature_list_by_plugin(gstRegistry, Str.toStringz(name));
371 		
372 		if(p is null)
373 		{
374 			return null;
375 		}
376 		
377 		return new ListG(cast(GList*) p);
378 	}
379 
380 	/**
381 	 * Returns the registry's feature list cookie. This changes
382 	 * every time a feature is added or removed from the registry.
383 	 *
384 	 * Return: the feature list cookie.
385 	 */
386 	public uint getFeatureListCookie()
387 	{
388 		return gst_registry_get_feature_list_cookie(gstRegistry);
389 	}
390 
391 	/**
392 	 * Get a copy of all plugins registered in the given registry. The refcount
393 	 * of each element in the list in incremented.
394 	 *
395 	 * Return: a #GList of #GstPlugin.
396 	 *     Use gst_plugin_list_free() after usage.
397 	 *
398 	 *     MT safe.
399 	 */
400 	public ListG getPluginList()
401 	{
402 		auto p = gst_registry_get_plugin_list(gstRegistry);
403 		
404 		if(p is null)
405 		{
406 			return null;
407 		}
408 		
409 		return new ListG(cast(GList*) p);
410 	}
411 
412 	/**
413 	 * Look up a plugin in the given registry with the given filename.
414 	 * If found, plugin is reffed.
415 	 *
416 	 * Params:
417 	 *     filename = the name of the file to look up
418 	 *
419 	 * Return: the #GstPlugin if found, or
420 	 *     %NULL if not.  gst_object_unref() after usage.
421 	 */
422 	public Plugin lookup(string filename)
423 	{
424 		auto p = gst_registry_lookup(gstRegistry, Str.toStringz(filename));
425 		
426 		if(p is null)
427 		{
428 			return null;
429 		}
430 		
431 		return ObjectG.getDObject!(Plugin)(cast(GstPlugin*) p, true);
432 	}
433 
434 	/**
435 	 * Find a #GstPluginFeature with @name in @registry.
436 	 *
437 	 * Params:
438 	 *     name = a #GstPluginFeature name
439 	 *
440 	 * Return: a #GstPluginFeature with its refcount incremented,
441 	 *     use gst_object_unref() after usage.
442 	 *
443 	 *     MT safe.
444 	 */
445 	public PluginFeature lookupFeature(string name)
446 	{
447 		auto p = gst_registry_lookup_feature(gstRegistry, Str.toStringz(name));
448 		
449 		if(p is null)
450 		{
451 			return null;
452 		}
453 		
454 		return ObjectG.getDObject!(PluginFeature)(cast(GstPluginFeature*) p, true);
455 	}
456 
457 	/**
458 	 * Runs a filter against all plugins in the registry and returns a #GList with
459 	 * the results. If the first flag is set, only the first match is
460 	 * returned (as a list with a single object).
461 	 * Every plugin is reffed; use gst_plugin_list_free() after use, which
462 	 * will unref again.
463 	 *
464 	 * Params:
465 	 *     filter = the filter to use
466 	 *     first = only return first match
467 	 *     userData = user data passed to the filter function
468 	 *
469 	 * Return: a #GList of #GstPlugin.
470 	 *     Use gst_plugin_list_free() after usage.
471 	 *
472 	 *     MT safe.
473 	 */
474 	public ListG pluginFilter(GstPluginFilter filter, bool first, void* userData)
475 	{
476 		auto p = gst_registry_plugin_filter(gstRegistry, filter, first, userData);
477 		
478 		if(p is null)
479 		{
480 			return null;
481 		}
482 		
483 		return new ListG(cast(GList*) p);
484 	}
485 
486 	/**
487 	 * Remove the feature from the registry.
488 	 *
489 	 * MT safe.
490 	 *
491 	 * Params:
492 	 *     feature = the feature to remove
493 	 */
494 	public void removeFeature(PluginFeature feature)
495 	{
496 		gst_registry_remove_feature(gstRegistry, (feature is null) ? null : feature.getPluginFeatureStruct());
497 	}
498 
499 	/**
500 	 * Remove the plugin from the registry.
501 	 *
502 	 * MT safe.
503 	 *
504 	 * Params:
505 	 *     plugin = the plugin to remove
506 	 */
507 	public void removePlugin(Plugin plugin)
508 	{
509 		gst_registry_remove_plugin(gstRegistry, (plugin is null) ? null : plugin.getPluginStruct());
510 	}
511 
512 	/**
513 	 * Scan the given path for plugins to add to the registry. The syntax of the
514 	 * path is specific to the registry.
515 	 *
516 	 * Params:
517 	 *     path = the path to scan
518 	 *
519 	 * Return: %TRUE if registry changed
520 	 */
521 	public bool scanPath(string path)
522 	{
523 		return gst_registry_scan_path(gstRegistry, Str.toStringz(path)) != 0;
524 	}
525 
526 	int[string] connectedSignals;
527 
528 	void delegate(PluginFeature, Registry)[] onFeatureAddedListeners;
529 	/**
530 	 * Signals that a feature has been added to the registry (possibly
531 	 * replacing a previously-added one by the same name)
532 	 *
533 	 * Params:
534 	 *     feature = the feature that has been added
535 	 */
536 	void addOnFeatureAdded(void delegate(PluginFeature, Registry) dlg, ConnectFlags connectFlags=cast(ConnectFlags)0)
537 	{
538 		if ( "feature-added" !in connectedSignals )
539 		{
540 			Signals.connectData(
541 				this,
542 				"feature-added",
543 				cast(GCallback)&callBackFeatureAdded,
544 				cast(void*)this,
545 				null,
546 				connectFlags);
547 			connectedSignals["feature-added"] = 1;
548 		}
549 		onFeatureAddedListeners ~= dlg;
550 	}
551 	extern(C) static void callBackFeatureAdded(GstRegistry* registryStruct, GstPluginFeature* feature, Registry _registry)
552 	{
553 		foreach ( void delegate(PluginFeature, Registry) dlg; _registry.onFeatureAddedListeners )
554 		{
555 			dlg(ObjectG.getDObject!(PluginFeature)(feature), _registry);
556 		}
557 	}
558 
559 	void delegate(Plugin, Registry)[] onPluginAddedListeners;
560 	/**
561 	 * Signals that a plugin has been added to the registry (possibly
562 	 * replacing a previously-added one by the same name)
563 	 *
564 	 * Params:
565 	 *     plugin = the plugin that has been added
566 	 */
567 	void addOnPluginAdded(void delegate(Plugin, Registry) dlg, ConnectFlags connectFlags=cast(ConnectFlags)0)
568 	{
569 		if ( "plugin-added" !in connectedSignals )
570 		{
571 			Signals.connectData(
572 				this,
573 				"plugin-added",
574 				cast(GCallback)&callBackPluginAdded,
575 				cast(void*)this,
576 				null,
577 				connectFlags);
578 			connectedSignals["plugin-added"] = 1;
579 		}
580 		onPluginAddedListeners ~= dlg;
581 	}
582 	extern(C) static void callBackPluginAdded(GstRegistry* registryStruct, GstPlugin* plugin, Registry _registry)
583 	{
584 		foreach ( void delegate(Plugin, Registry) dlg; _registry.onPluginAddedListeners )
585 		{
586 			dlg(ObjectG.getDObject!(Plugin)(plugin), _registry);
587 		}
588 	}
589 }