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 }