gst/gstplugin.h

   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 #ifdef G_DEFINE_AUTOPTR_CLEANUP_FUNC
 399 G_DEFINE_AUTOPTR_CLEANUP_FUNC(GstPlugin, gst_object_unref)
 400 #endif
 401
 402 G_END_DECLS
 403
 404 #endif /* __GST_PLUGIN_H__ */