1 /* GStreamer 2 * Copyright (C) 1999,2000 Erik Walthinsen <omega@cse.ogi.edu> 3 * 2000 Wim Taymans <wtay@chello.be> 4 * 5 * gstplugin.h: Header for plugin subsystem 6 * 7 * This library is free software; you can redistribute it and/or 8 * modify it under the terms of the GNU Library General Public 9 * License as published by the Free Software Foundation; either 10 * version 2 of the License, or (at your option) any later version. 11 * 12 * This library is distributed in the hope that it will be useful, 13 * but WITHOUT ANY WARRANTY; without even the implied warranty of 14 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 15 * Library General Public License for more details. 16 * 17 * You should have received a copy of the GNU Library General Public 18 * License along with this library; if not, write to the 19 * Free Software Foundation, Inc., 51 Franklin St, Fifth Floor, 20 * Boston, MA 02110-1301, USA. 21 */ 22 23 24 #ifndef __GST_PLUGIN_H__ 25 #define __GST_PLUGIN_H__ 26 27 #include <gst/gstconfig.h> 28 29 #include <gst/gstobject.h> 30 #include <gst/gstmacros.h> 31 #include <gst/gststructure.h> 32 33 G_BEGIN_DECLS 34 35 /** 36 * GstPlugin: 37 * 38 * The opaque plugin object 39 */ 40 typedef struct _GstPlugin GstPlugin; 41 typedef struct _GstPluginClass GstPluginClass; 42 typedef struct _GstPluginDesc GstPluginDesc; 43 44 /** 45 * gst_plugin_error_quark: 46 * 47 * Get the error quark. 48 * 49 * Returns: The error quark used in GError messages 50 */ 51 52 GST_API 53 GQuark gst_plugin_error_quark (void); 54 /** 55 * GST_PLUGIN_ERROR: 56 * 57 * The error message category quark 58 */ 59 #define GST_PLUGIN_ERROR gst_plugin_error_quark () 60 61 /** 62 * GstPluginError: 63 * @GST_PLUGIN_ERROR_MODULE: The plugin could not be loaded 64 * @GST_PLUGIN_ERROR_DEPENDENCIES: The plugin has unresolved dependencies 65 * @GST_PLUGIN_ERROR_NAME_MISMATCH: The plugin has already be loaded from a different file 66 * 67 * The plugin loading errors 68 */ 69 typedef enum 70 { 71 GST_PLUGIN_ERROR_MODULE, 72 GST_PLUGIN_ERROR_DEPENDENCIES, 73 GST_PLUGIN_ERROR_NAME_MISMATCH 74 } GstPluginError; 75 76 /** 77 * GstPluginFlags: 78 * @GST_PLUGIN_FLAG_CACHED: Temporarily loaded plugins 79 * @GST_PLUGIN_FLAG_BLACKLISTED: The plugin won't be scanned (again) 80 * 81 * The plugin loading state 82 */ 83 typedef enum 84 { 85 GST_PLUGIN_FLAG_CACHED = (GST_OBJECT_FLAG_LAST << 0), 86 GST_PLUGIN_FLAG_BLACKLISTED = (GST_OBJECT_FLAG_LAST << 1) 87 } GstPluginFlags; 88 89 /** 90 * GstPluginDependencyFlags: 91 * @GST_PLUGIN_DEPENDENCY_FLAG_NONE : no special flags 92 * @GST_PLUGIN_DEPENDENCY_FLAG_RECURSE : recurse into subdirectories 93 * @GST_PLUGIN_DEPENDENCY_FLAG_PATHS_ARE_DEFAULT_ONLY : use paths 94 * argument only if none of the environment variables is set 95 * @GST_PLUGIN_DEPENDENCY_FLAG_FILE_NAME_IS_SUFFIX : interpret 96 * filename argument as filter suffix and check all matching files in 97 * the directory 98 * @GST_PLUGIN_DEPENDENCY_FLAG_FILE_NAME_IS_PREFIX : interpret 99 * filename argument as filter prefix and check all matching files in 100 * the directory. Since: 1.8. 101 * @GST_PLUGIN_DEPENDENCY_FLAG_PATHS_ARE_RELATIVE_TO_EXE : interpret 102 * non-absolute paths as relative to the main executable directory. Since 103 * 1.14. 104 * 105 * Flags used in connection with gst_plugin_add_dependency(). 106 */ 107 typedef enum { 108 GST_PLUGIN_DEPENDENCY_FLAG_NONE = 0, 109 GST_PLUGIN_DEPENDENCY_FLAG_RECURSE = (1 << 0), 110 GST_PLUGIN_DEPENDENCY_FLAG_PATHS_ARE_DEFAULT_ONLY = (1 << 1), 111 GST_PLUGIN_DEPENDENCY_FLAG_FILE_NAME_IS_SUFFIX = (1 << 2), 112 GST_PLUGIN_DEPENDENCY_FLAG_FILE_NAME_IS_PREFIX = (1 << 3), 113 GST_PLUGIN_DEPENDENCY_FLAG_PATHS_ARE_RELATIVE_TO_EXE = (1 << 4) 114 } GstPluginDependencyFlags; 115 116 /** 117 * GstPluginInitFunc: 118 * @plugin: The plugin object 119 * 120 * A plugin should provide a pointer to a function of this type in the 121 * plugin_desc struct. 122 * This function will be called by the loader at startup. One would then 123 * register each #GstPluginFeature. 124 * 125 * Returns: %TRUE if plugin initialised successfully 126 */ 127 /* FIXME 0.11: Make return void */ 128 typedef gboolean (*GstPluginInitFunc) (GstPlugin *plugin); 129 130 /** 131 * GstPluginInitFullFunc: 132 * @plugin: The plugin object 133 * @user_data: extra data 134 * 135 * A plugin should provide a pointer to a function of either #GstPluginInitFunc 136 * or this type in the plugin_desc struct. 137 * The function will be called by the loader at startup. One would then 138 * register each #GstPluginFeature. This version allows 139 * user data to be passed to init function (useful for bindings). 140 * 141 * Returns: %TRUE if plugin initialised successfully 142 */ 143 /* FIXME 0.11: Merge with GstPluginInitFunc */ 144 typedef gboolean (*GstPluginInitFullFunc) (GstPlugin *plugin, gpointer user_data); 145 146 /** 147 * GstPluginDesc: 148 * @major_version: the major version number of core that plugin was compiled for 149 * @minor_version: the minor version number of core that plugin was compiled for 150 * @name: a unique name of the plugin 151 * @description: description of plugin 152 * @plugin_init: pointer to the init function of this plugin. 153 * @version: version of the plugin 154 * @license: effective license of plugin 155 * @source: source module plugin belongs to 156 * @package: shipped package plugin belongs to 157 * @origin: URL to provider of plugin 158 * @release_datetime: (allow-none): date time string in ISO 8601 159 * format (or rather, a subset thereof), or %NULL. Allowed are the 160 * following formats: "YYYY-MM-DD" and "YYY-MM-DDTHH:MMZ" (with 161 * 'T' a separator and 'Z' indicating UTC/Zulu time). This field 162 * should be set via the GST_PACKAGE_RELEASE_DATETIME 163 * preprocessor macro. 164 * 165 * A plugin should export a variable of this type called plugin_desc. The plugin 166 * loader will use the data provided there to initialize the plugin. 167 * 168 * The @licence parameter must be one of: LGPL, GPL, QPL, GPL/QPL, MPL, 169 * BSD, MIT/X11, Proprietary, unknown. 170 */ 171 struct _GstPluginDesc { 172 gint major_version; 173 gint minor_version; 174 const gchar *name; 175 const gchar *description; 176 GstPluginInitFunc plugin_init; 177 const gchar *version; 178 const gchar *license; 179 const gchar *source; 180 const gchar *package; 181 const gchar *origin; 182 const gchar *release_datetime; 183 /*< private >*/ 184 gpointer _gst_reserved[GST_PADDING]; 185 }; 186 187 188 #define GST_TYPE_PLUGIN (gst_plugin_get_type()) 189 #define GST_IS_PLUGIN(obj) (G_TYPE_CHECK_INSTANCE_TYPE ((obj), GST_TYPE_PLUGIN)) 190 #define GST_IS_PLUGIN_CLASS(klass) (G_TYPE_CHECK_CLASS_TYPE ((klass), GST_TYPE_PLUGIN)) 191 #define GST_PLUGIN_GET_CLASS(obj) (G_TYPE_INSTANCE_GET_CLASS ((obj), GST_TYPE_PLUGIN, GstPluginClass)) 192 #define GST_PLUGIN(obj) (G_TYPE_CHECK_INSTANCE_CAST ((obj), GST_TYPE_PLUGIN, GstPlugin)) 193 #define GST_PLUGIN_CLASS(klass) (G_TYPE_CHECK_CLASS_CAST ((klass), GST_TYPE_PLUGIN, GstPluginClass)) 194 #define GST_PLUGIN_CAST(obj) ((GstPlugin*)(obj)) 195 196 #ifdef GST_PACKAGE_RELEASE_DATETIME 197 #define __GST_PACKAGE_RELEASE_DATETIME GST_PACKAGE_RELEASE_DATETIME 198 #else 199 #define __GST_PACKAGE_RELEASE_DATETIME NULL 200 #endif 201 202 /** 203 * GST_PLUGIN_STATIC_DECLARE: 204 * @name: short, but unique name of the plugin 205 * 206 * This macro can be used to initialize statically linked plugins. It is 207 * necessary to call this macro before the plugin can be used. 208 * It has to be used in combination with GST_PLUGIN_STATIC_REGISTER 209 * and must be placed outside any block to declare the plugin initialization 210 * function. 211 * 212 * Since: 1.2 213 */ 214 #define GST_PLUGIN_STATIC_DECLARE(name) \ 215 extern void G_PASTE(gst_plugin_, G_PASTE(name, _register)) (void) 216 217 /** 218 * GST_PLUGIN_STATIC_REGISTER: 219 * @name: short, but unique name of the plugin 220 * 221 * This macro can be used to initialize statically linked plugins. It is 222 * necessary to call this macro before the plugin can be used. 223 * It has to be used in combination with GST_PLUGIN_STATIC_DECLARE and 224 * calls the plugin initialization function. 225 * 226 * Since: 1.2 227 */ 228 #define GST_PLUGIN_STATIC_REGISTER(name) G_PASTE(gst_plugin_, G_PASTE(name, _register)) () 229 230 /** 231 * GST_PLUGIN_DEFINE: 232 * @major: major version number of the gstreamer-core that plugin was compiled for 233 * @minor: minor version number of the gstreamer-core that plugin was compiled for 234 * @name: short, but unique name of the plugin 235 * @description: information about the purpose of the plugin 236 * @init: function pointer to the plugin_init method with the signature of <code>static gboolean plugin_init (GstPlugin * plugin)</code>. 237 * @version: full version string (e.g. VERSION from config.h) 238 * @license: under which licence the package has been released, e.g. GPL, LGPL. 239 * @package: the package-name (e.g. PACKAGE_NAME from config.h) 240 * @origin: a description from where the package comes from (e.g. the homepage URL) 241 * 242 * This macro needs to be used to define the entry point and meta data of a 243 * plugin. One would use this macro to export a plugin, so that it can be used 244 * by other applications. 245 * 246 * The macro uses a define named PACKAGE for the #GstPluginDesc,source field. 247 * When using autoconf, this is usually set automatically via the AC_INIT 248 * macro, and set in config.h. If you are not using autoconf, you will need to 249 * define PACKAGE yourself and set it to a short mnemonic string identifying 250 * your application/package, e.g. 'someapp' or 'my-plugins-foo. 251 * 252 * If defined, the GST_PACKAGE_RELEASE_DATETIME will also be used for the 253 * #GstPluginDesc,release_datetime field. 254 */ 255 #define GST_PLUGIN_DEFINE(major,minor,name,description,init,version,license,package,origin) \ 256 G_BEGIN_DECLS \ 257 GST_PLUGIN_EXPORT const GstPluginDesc * G_PASTE(gst_plugin_, G_PASTE(name, _get_desc)) (void); \ 258 GST_PLUGIN_EXPORT void G_PASTE(gst_plugin_, G_PASTE(name, _register)) (void); \ 259 \ 260 static const GstPluginDesc gst_plugin_desc = { \ 261 major, \ 262 minor, \ 263 G_STRINGIFY(name), \ 264 (gchar *) description, \ 265 init, \ 266 version, \ 267 license, \ 268 PACKAGE, \ 269 package, \ 270 origin, \ 271 __GST_PACKAGE_RELEASE_DATETIME, \ 272 GST_PADDING_INIT \ 273 }; \ 274 \ 275 const GstPluginDesc * \ 276 G_PASTE(gst_plugin_, G_PASTE(name, _get_desc)) (void) \ 277 { \ 278 return &gst_plugin_desc; \ 279 } \ 280 \ 281 void \ 282 G_PASTE(gst_plugin_, G_PASTE(name, _register)) (void) \ 283 { \ 284 gst_plugin_register_static (major, minor, G_STRINGIFY(name), \ 285 description, init, version, license, \ 286 PACKAGE, package, origin); \ 287 } \ 288 G_END_DECLS 289 290 /** 291 * GST_LICENSE_UNKNOWN: 292 * 293 * To be used in GST_PLUGIN_DEFINE if unsure about the licence. 294 */ 295 #define GST_LICENSE_UNKNOWN "unknown" 296 297 298 /* function for filters */ 299 /** 300 * GstPluginFilter: 301 * @plugin: the plugin to check 302 * @user_data: the user_data that has been passed on e.g. gst_registry_plugin_filter() 303 * 304 * A function that can be used with e.g. gst_registry_plugin_filter() 305 * to get a list of plugins that match certain criteria. 306 * 307 * Returns: %TRUE for a positive match, %FALSE otherwise 308 */ 309 typedef gboolean (*GstPluginFilter) (GstPlugin *plugin, 310 gpointer user_data); 311 312 GST_API 313 GType gst_plugin_get_type (void); 314 315 GST_API 316 gboolean gst_plugin_register_static (gint major_version, 317 gint minor_version, 318 const gchar *name, 319 const gchar *description, 320 GstPluginInitFunc init_func, 321 const gchar *version, 322 const gchar *license, 323 const gchar *source, 324 const gchar *package, 325 const gchar *origin); 326 GST_API 327 gboolean gst_plugin_register_static_full (gint major_version, 328 gint minor_version, 329 const gchar *name, 330 const gchar *description, 331 GstPluginInitFullFunc init_full_func, 332 const gchar *version, 333 const gchar *license, 334 const gchar *source, 335 const gchar *package, 336 const gchar *origin, 337 gpointer user_data); 338 GST_API 339 const gchar* gst_plugin_get_name (GstPlugin *plugin); 340 341 GST_API 342 const gchar* gst_plugin_get_description (GstPlugin *plugin); 343 344 GST_API 345 const gchar* gst_plugin_get_filename (GstPlugin *plugin); 346 347 GST_API 348 const gchar* gst_plugin_get_version (GstPlugin *plugin); 349 350 GST_API 351 const gchar* gst_plugin_get_license (GstPlugin *plugin); 352 353 GST_API 354 const gchar* gst_plugin_get_source (GstPlugin *plugin); 355 356 GST_API 357 const gchar* gst_plugin_get_package (GstPlugin *plugin); 358 359 GST_API 360 const gchar* gst_plugin_get_origin (GstPlugin *plugin); 361 362 GST_API 363 const gchar* gst_plugin_get_release_date_string (GstPlugin *plugin); 364 365 GST_API 366 const GstStructure* gst_plugin_get_cache_data (GstPlugin * plugin); 367 368 GST_API 369 void gst_plugin_set_cache_data (GstPlugin * plugin, GstStructure *cache_data); 370 371 GST_API 372 gboolean gst_plugin_is_loaded (GstPlugin *plugin); 373 374 GST_API 375 GstPlugin * gst_plugin_load_file (const gchar *filename, GError** error); 376 377 GST_API 378 GstPlugin * gst_plugin_load (GstPlugin *plugin); 379 380 GST_API 381 GstPlugin * gst_plugin_load_by_name (const gchar *name); 382 383 GST_API 384 void gst_plugin_add_dependency (GstPlugin * plugin, 385 const gchar ** env_vars, 386 const gchar ** paths, 387 const gchar ** names, 388 GstPluginDependencyFlags flags); 389 GST_API 390 void gst_plugin_add_dependency_simple (GstPlugin * plugin, 391 const gchar * env_vars, 392 const gchar * paths, 393 const gchar * names, 394 GstPluginDependencyFlags flags); 395 GST_API 396 void gst_plugin_list_free (GList *list); 397 398 G_DEFINE_AUTOPTR_CLEANUP_FUNC(GstPlugin, gst_object_unref) 399 400 G_END_DECLS 401 402 #endif /* __GST_PLUGIN_H__ */ 403