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