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.Plugin;
26 
27 private import glib.ErrorG;
28 private import glib.GException;
29 private import glib.ListG;
30 private import glib.Str;
31 private import gobject.ObjectG;
32 private import gstreamer.ObjectGst;
33 private import gstreamer.Structure;
34 private import gstreamerc.gstreamer;
35 public  import gstreamerc.gstreamertypes;
36 
37 
38 /**
39  * GStreamer is extensible, so #GstElement instances can be loaded at runtime.
40  * A plugin system can provide one or more of the basic
41  * <application>GStreamer</application> #GstPluginFeature subclasses.
42  * 
43  * A plugin should export a symbol <symbol>gst_plugin_desc</symbol> that is a
44  * struct of type #GstPluginDesc.
45  * the plugin loader will check the version of the core library the plugin was
46  * linked against and will create a new #GstPlugin. It will then call the
47  * #GstPluginInitFunc function that was provided in the
48  * <symbol>gst_plugin_desc</symbol>.
49  * 
50  * Once you have a handle to a #GstPlugin (e.g. from the #GstRegistry), you
51  * can add any object that subclasses #GstPluginFeature.
52  * 
53  * Usually plugins are always automatically loaded so you don't need to call
54  * gst_plugin_load() explicitly to bring it into memory. There are options to
55  * statically link plugins to an app or even use GStreamer without a plugin
56  * repository in which case gst_plugin_load() can be needed to bring the plugin
57  * into memory.
58  */
59 public class Plugin : ObjectGst
60 {
61 	/** the main Gtk struct */
62 	protected GstPlugin* gstPlugin;
63 
64 	/** Get the main Gtk struct */
65 	public GstPlugin* getPluginStruct()
66 	{
67 		return gstPlugin;
68 	}
69 
70 	/** the main Gtk struct as a void* */
71 	protected override void* getStruct()
72 	{
73 		return cast(void*)gstPlugin;
74 	}
75 
76 	protected override void setStruct(GObject* obj)
77 	{
78 		gstPlugin = cast(GstPlugin*)obj;
79 		super.setStruct(obj);
80 	}
81 
82 	/**
83 	 * Sets our main struct and passes it to the parent class.
84 	 */
85 	public this (GstPlugin* gstPlugin, bool ownedRef = false)
86 	{
87 		this.gstPlugin = gstPlugin;
88 		super(cast(GstObject*)gstPlugin, ownedRef);
89 	}
90 
91 
92 	/** */
93 	public static GType getType()
94 	{
95 		return gst_plugin_get_type();
96 	}
97 
98 	/**
99 	 * Unrefs each member of @list, then frees the list.
100 	 *
101 	 * Params:
102 	 *     list = list of #GstPlugin
103 	 */
104 	public static void listFree(ListG list)
105 	{
106 		gst_plugin_list_free((list is null) ? null : list.getListGStruct());
107 	}
108 
109 	/**
110 	 * Load the named plugin. Refs the plugin.
111 	 *
112 	 * Params:
113 	 *     name = name of plugin to load
114 	 *
115 	 * Return: a reference to a loaded plugin, or %NULL on error.
116 	 */
117 	public static Plugin loadByName(string name)
118 	{
119 		auto p = gst_plugin_load_by_name(Str.toStringz(name));
120 		
121 		if(p is null)
122 		{
123 			return null;
124 		}
125 		
126 		return ObjectG.getDObject!(Plugin)(cast(GstPlugin*) p, true);
127 	}
128 
129 	/**
130 	 * Loads the given plugin and refs it.  Caller needs to unref after use.
131 	 *
132 	 * Params:
133 	 *     filename = the plugin filename to load
134 	 *
135 	 * Return: a reference to the existing loaded GstPlugin, a
136 	 *     reference to the newly-loaded GstPlugin, or %NULL if an error occurred.
137 	 *
138 	 * Throws: GException on failure.
139 	 */
140 	public static Plugin loadFile(string filename)
141 	{
142 		GError* err = null;
143 		
144 		auto p = gst_plugin_load_file(Str.toStringz(filename), &err);
145 		
146 		if (err !is null)
147 		{
148 			throw new GException( new ErrorG(err) );
149 		}
150 		
151 		if(p is null)
152 		{
153 			return null;
154 		}
155 		
156 		return ObjectG.getDObject!(Plugin)(cast(GstPlugin*) p, true);
157 	}
158 
159 	/**
160 	 * Registers a static plugin, ie. a plugin which is private to an application
161 	 * or library and contained within the application or library (as opposed to
162 	 * being shipped as a separate module file).
163 	 *
164 	 * You must make sure that GStreamer has been initialised (with gst_init() or
165 	 * via gst_init_get_option_group()) before calling this function.
166 	 *
167 	 * Params:
168 	 *     majorVersion = the major version number of the GStreamer core that the
169 	 *         plugin was compiled for, you can just use GST_VERSION_MAJOR here
170 	 *     minorVersion = the minor version number of the GStreamer core that the
171 	 *         plugin was compiled for, you can just use GST_VERSION_MINOR here
172 	 *     name = a unique name of the plugin (ideally prefixed with an application- or
173 	 *         library-specific namespace prefix in order to avoid name conflicts in
174 	 *         case a similar plugin with the same name ever gets added to GStreamer)
175 	 *     description = description of the plugin
176 	 *     initFunc = pointer to the init function of this plugin.
177 	 *     versio = version string of the plugin
178 	 *     license = effective license of plugin. Must be one of the approved licenses
179 	 *         (see #GstPluginDesc above) or the plugin will not be registered.
180 	 *     source = source module plugin belongs to
181 	 *     p = shipped package plugin belongs to
182 	 *     origin = URL to provider of plugin
183 	 *
184 	 * Return: %TRUE if the plugin was registered correctly, otherwise %FALSE.
185 	 */
186 	public static bool registerStatic(int majorVersion, int minorVersion, string name, string description, GstPluginInitFunc initFunc, string versio, string license, string source, string p, string origin)
187 	{
188 		return gst_plugin_register_static(majorVersion, minorVersion, Str.toStringz(name), Str.toStringz(description), initFunc, Str.toStringz(versio), Str.toStringz(license), Str.toStringz(source), Str.toStringz(p), Str.toStringz(origin)) != 0;
189 	}
190 
191 	/**
192 	 * Registers a static plugin, ie. a plugin which is private to an application
193 	 * or library and contained within the application or library (as opposed to
194 	 * being shipped as a separate module file) with a #GstPluginInitFullFunc
195 	 * which allows user data to be passed to the callback function (useful
196 	 * for bindings).
197 	 *
198 	 * You must make sure that GStreamer has been initialised (with gst_init() or
199 	 * via gst_init_get_option_group()) before calling this function.
200 	 *
201 	 * Params:
202 	 *     majorVersion = the major version number of the GStreamer core that the
203 	 *         plugin was compiled for, you can just use GST_VERSION_MAJOR here
204 	 *     minorVersion = the minor version number of the GStreamer core that the
205 	 *         plugin was compiled for, you can just use GST_VERSION_MINOR here
206 	 *     name = a unique name of the plugin (ideally prefixed with an application- or
207 	 *         library-specific namespace prefix in order to avoid name conflicts in
208 	 *         case a similar plugin with the same name ever gets added to GStreamer)
209 	 *     description = description of the plugin
210 	 *     initFullFunc = pointer to the init function with user data
211 	 *         of this plugin.
212 	 *     versio = version string of the plugin
213 	 *     license = effective license of plugin. Must be one of the approved licenses
214 	 *         (see #GstPluginDesc above) or the plugin will not be registered.
215 	 *     source = source module plugin belongs to
216 	 *     p = shipped package plugin belongs to
217 	 *     origin = URL to provider of plugin
218 	 *     userData = gpointer to user data
219 	 *
220 	 * Return: %TRUE if the plugin was registered correctly, otherwise %FALSE.
221 	 */
222 	public static bool registerStaticFull(int majorVersion, int minorVersion, string name, string description, GstPluginInitFullFunc initFullFunc, string versio, string license, string source, string p, string origin, void* userData)
223 	{
224 		return gst_plugin_register_static_full(majorVersion, minorVersion, Str.toStringz(name), Str.toStringz(description), initFullFunc, Str.toStringz(versio), Str.toStringz(license), Str.toStringz(source), Str.toStringz(p), Str.toStringz(origin), userData) != 0;
225 	}
226 
227 	/**
228 	 * Make GStreamer aware of external dependencies which affect the feature
229 	 * set of this plugin (ie. the elements or typefinders associated with it).
230 	 *
231 	 * GStreamer will re-inspect plugins with external dependencies whenever any
232 	 * of the external dependencies change. This is useful for plugins which wrap
233 	 * other plugin systems, e.g. a plugin which wraps a plugin-based visualisation
234 	 * library and makes visualisations available as GStreamer elements, or a
235 	 * codec loader which exposes elements and/or caps dependent on what external
236 	 * codec libraries are currently installed.
237 	 *
238 	 * Params:
239 	 *     envVars = %NULL-terminated array of environment variables affecting the
240 	 *         feature set of the plugin (e.g. an environment variable containing
241 	 *         paths where to look for additional modules/plugins of a library),
242 	 *         or %NULL. Environment variable names may be followed by a path component
243 	 *         which will be added to the content of the environment variable, e.g.
244 	 *         "HOME/.mystuff/plugins".
245 	 *     paths = %NULL-terminated array of directories/paths where dependent files
246 	 *         may be, or %NULL.
247 	 *     names = %NULL-terminated array of file names (or file name suffixes,
248 	 *         depending on @flags) to be used in combination with the paths from
249 	 *         @paths and/or the paths extracted from the environment variables in
250 	 *         @env_vars, or %NULL.
251 	 *     flags = optional flags, or #GST_PLUGIN_DEPENDENCY_FLAG_NONE
252 	 */
253 	public void addDependency(string[] envVars, string[] paths, string[] names, GstPluginDependencyFlags flags)
254 	{
255 		gst_plugin_add_dependency(gstPlugin, Str.toStringzArray(envVars), Str.toStringzArray(paths), Str.toStringzArray(names), flags);
256 	}
257 
258 	/**
259 	 * Make GStreamer aware of external dependencies which affect the feature
260 	 * set of this plugin (ie. the elements or typefinders associated with it).
261 	 *
262 	 * GStreamer will re-inspect plugins with external dependencies whenever any
263 	 * of the external dependencies change. This is useful for plugins which wrap
264 	 * other plugin systems, e.g. a plugin which wraps a plugin-based visualisation
265 	 * library and makes visualisations available as GStreamer elements, or a
266 	 * codec loader which exposes elements and/or caps dependent on what external
267 	 * codec libraries are currently installed.
268 	 *
269 	 * Convenience wrapper function for gst_plugin_add_dependency() which
270 	 * takes simple strings as arguments instead of string arrays, with multiple
271 	 * arguments separated by predefined delimiters (see above).
272 	 *
273 	 * Params:
274 	 *     envVars = one or more environment variables (separated by ':', ';' or ','),
275 	 *         or %NULL. Environment variable names may be followed by a path component
276 	 *         which will be added to the content of the environment variable, e.g.
277 	 *         "HOME/.mystuff/plugins:MYSTUFF_PLUGINS_PATH"
278 	 *     paths = one ore more directory paths (separated by ':' or ';' or ','),
279 	 *         or %NULL. Example: "/usr/lib/mystuff/plugins"
280 	 *     names = one or more file names or file name suffixes (separated by commas),
281 	 *         or %NULL
282 	 *     flags = optional flags, or #GST_PLUGIN_DEPENDENCY_FLAG_NONE
283 	 */
284 	public void addDependencySimple(string envVars, string paths, string names, GstPluginDependencyFlags flags)
285 	{
286 		gst_plugin_add_dependency_simple(gstPlugin, Str.toStringz(envVars), Str.toStringz(paths), Str.toStringz(names), flags);
287 	}
288 
289 	/**
290 	 * Gets the plugin specific data cache. If it is %NULL there is no cached data
291 	 * stored. This is the case when the registry is getting rebuilt.
292 	 *
293 	 * Return: The cached data as a
294 	 *     #GstStructure or %NULL.
295 	 */
296 	public Structure getCacheData()
297 	{
298 		auto p = gst_plugin_get_cache_data(gstPlugin);
299 		
300 		if(p is null)
301 		{
302 			return null;
303 		}
304 		
305 		return ObjectG.getDObject!(Structure)(cast(GstStructure*) p);
306 	}
307 
308 	/**
309 	 * Get the long descriptive name of the plugin
310 	 *
311 	 * Return: the long name of the plugin
312 	 */
313 	public string getDescription()
314 	{
315 		return Str.toString(gst_plugin_get_description(gstPlugin));
316 	}
317 
318 	/**
319 	 * get the filename of the plugin
320 	 *
321 	 * Return: the filename of the plugin
322 	 */
323 	public string getFilename()
324 	{
325 		return Str.toString(gst_plugin_get_filename(gstPlugin));
326 	}
327 
328 	/**
329 	 * get the license of the plugin
330 	 *
331 	 * Return: the license of the plugin
332 	 */
333 	public string getLicense()
334 	{
335 		return Str.toString(gst_plugin_get_license(gstPlugin));
336 	}
337 
338 	/**
339 	 * Get the short name of the plugin
340 	 *
341 	 * Return: the name of the plugin
342 	 */
343 	public override string getName()
344 	{
345 		return Str.toString(gst_plugin_get_name(gstPlugin));
346 	}
347 
348 	/**
349 	 * get the URL where the plugin comes from
350 	 *
351 	 * Return: the origin of the plugin
352 	 */
353 	public string getOrigin()
354 	{
355 		return Str.toString(gst_plugin_get_origin(gstPlugin));
356 	}
357 
358 	/**
359 	 * get the package the plugin belongs to.
360 	 *
361 	 * Return: the package of the plugin
362 	 */
363 	public string getPackage()
364 	{
365 		return Str.toString(gst_plugin_get_package(gstPlugin));
366 	}
367 
368 	/**
369 	 * Get the release date (and possibly time) in form of a string, if available.
370 	 *
371 	 * For normal GStreamer plugin releases this will usually just be a date in
372 	 * the form of "YYYY-MM-DD", while pre-releases and builds from git may contain
373 	 * a time component after the date as well, in which case the string will be
374 	 * formatted like "YYYY-MM-DDTHH:MMZ" (e.g. "2012-04-30T09:30Z").
375 	 *
376 	 * There may be plugins that do not have a valid release date set on them.
377 	 *
378 	 * Return: the date string of the plugin, or %NULL if not
379 	 *     available.
380 	 */
381 	public string getReleaseDateString()
382 	{
383 		return Str.toString(gst_plugin_get_release_date_string(gstPlugin));
384 	}
385 
386 	/**
387 	 * get the source module the plugin belongs to.
388 	 *
389 	 * Return: the source of the plugin
390 	 */
391 	public string getSource()
392 	{
393 		return Str.toString(gst_plugin_get_source(gstPlugin));
394 	}
395 
396 	/**
397 	 * get the version of the plugin
398 	 *
399 	 * Return: the version of the plugin
400 	 */
401 	public string getVersion()
402 	{
403 		return Str.toString(gst_plugin_get_version(gstPlugin));
404 	}
405 
406 	/**
407 	 * queries if the plugin is loaded into memory
408 	 *
409 	 * Return: %TRUE is loaded, %FALSE otherwise
410 	 */
411 	public bool isLoaded()
412 	{
413 		return gst_plugin_is_loaded(gstPlugin) != 0;
414 	}
415 
416 	/**
417 	 * Loads @plugin. Note that the *return value* is the loaded plugin; @plugin is
418 	 * untouched. The normal use pattern of this function goes like this:
419 	 *
420 	 * <programlisting>
421 	 * GstPlugin *loaded_plugin;
422 	 * loaded_plugin = gst_plugin_load (plugin);
423 	 * // presumably, we're no longer interested in the potentially-unloaded plugin
424 	 * gst_object_unref (plugin);
425 	 * plugin = loaded_plugin;
426 	 * </programlisting>
427 	 *
428 	 * Return: a reference to a loaded plugin, or %NULL on error.
429 	 */
430 	public Plugin load()
431 	{
432 		auto p = gst_plugin_load(gstPlugin);
433 		
434 		if(p is null)
435 		{
436 			return null;
437 		}
438 		
439 		return ObjectG.getDObject!(Plugin)(cast(GstPlugin*) p, true);
440 	}
441 
442 	/**
443 	 * Adds plugin specific data to cache. Passes the ownership of the structure to
444 	 * the @plugin.
445 	 *
446 	 * The cache is flushed every time the registry is rebuilt.
447 	 *
448 	 * Params:
449 	 *     cacheData = a structure containing the data to cache
450 	 */
451 	public void setCacheData(Structure cacheData)
452 	{
453 		gst_plugin_set_cache_data(gstPlugin, (cacheData is null) ? null : cacheData.getStructureStruct());
454 	}
455 
456 	/**
457 	 * Get the error quark.
458 	 *
459 	 * Return: The error quark used in GError messages
460 	 */
461 	public static GQuark pluginErrorQuark()
462 	{
463 		return gst_plugin_error_quark();
464 	}
465 }