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., 59 Temple Place - Suite 330,
  20  * Boston, MA 02111-1307, USA.
  21  */
  22
  23
  24 #ifndef __GST_PLUGIN_H__
  25 #define __GST_PLUGIN_H__
  26
  27 #include <gst/gstconfig.h>
  28
  29 #include <time.h> /* time_t */
  30 #include <sys/types.h> /* off_t */
  31 #include <sys/stat.h> /* off_t */
  32 #include <gmodule.h>
  33 #include <gst/gstobject.h>
  34 #include <gst/gstmacros.h>
  35 #include <gst/gststructure.h>
  36
  37 G_BEGIN_DECLS
  38
  39 typedef struct _GstPlugin GstPlugin;
  40 typedef struct _GstPluginClass GstPluginClass;
  41 typedef struct _GstPluginPrivate GstPluginPrivate;
  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 GQuark gst_plugin_error_quark (void);
  52 /**
  53  * GST_PLUGIN_ERROR:
  54  *
  55  * The error message category quark
  56  */
  57 #define GST_PLUGIN_ERROR gst_plugin_error_quark ()
  58
  59 /**
  60  * GstPluginError:
  61  * @GST_PLUGIN_ERROR_MODULE: The plugin could not be loaded
  62  * @GST_PLUGIN_ERROR_DEPENDENCIES: The plugin has unresolved dependencies
  63  * @GST_PLUGIN_ERROR_NAME_MISMATCH: The plugin has already be loaded from a different file
  64  *
  65  * The plugin loading errors
  66  */
  67 typedef enum
  68 {
  69   GST_PLUGIN_ERROR_MODULE,
  70   GST_PLUGIN_ERROR_DEPENDENCIES,
  71   GST_PLUGIN_ERROR_NAME_MISMATCH
  72 } GstPluginError;
  73
  74 /**
  75  * GstPluginFlags:
  76  * @GST_PLUGIN_FLAG_CACHED: Temporarily loaded plugins
  77  * @GST_PLUGIN_FLAG_BLACKLISTED: The plugin won't be scanned (again)
  78  *
  79  * The plugin loading state
  80  */
  81 typedef enum
  82 {
  83   GST_PLUGIN_FLAG_CACHED = (1<<0),
  84   GST_PLUGIN_FLAG_BLACKLISTED = (1<<1)
  85 } GstPluginFlags;
  86
  87 /**
  88  * GstPluginDependencyFlags:
  89  * @GST_PLUGIN_DEPENDENCY_FLAG_NONE : no special flags
  90  * @GST_PLUGIN_DEPENDENCY_FLAG_RECURSE : recurse into subdirectories
  91  * @GST_PLUGIN_DEPENDENCY_FLAG_PATHS_ARE_DEFAULT_ONLY : use paths
  92  *         argument only if none of the environment variables is set
  93  * @GST_PLUGIN_DEPENDENCY_FLAG_FILE_NAME_IS_SUFFIX : interpret
  94  *         filename argument as filter suffix and check all matching files in
  95  *         the directory
  96  *
  97  * Flags used in connection with gst_plugin_add_dependency().
  98  *
  99  * Since: 0.10.22
 100  */
 101 typedef enum {
 102   GST_PLUGIN_DEPENDENCY_FLAG_NONE = 0,
 103   GST_PLUGIN_DEPENDENCY_FLAG_RECURSE = (1 << 0),
 104   GST_PLUGIN_DEPENDENCY_FLAG_PATHS_ARE_DEFAULT_ONLY = (1 << 1),
 105   GST_PLUGIN_DEPENDENCY_FLAG_FILE_NAME_IS_SUFFIX = (1 << 2)
 106 } GstPluginDependencyFlags;
 107
 108 /**
 109  * GstPluginInitFunc:
 110  * @plugin: The plugin object
 111  *
 112  * A plugin should provide a pointer to a function of this type in the
 113  * plugin_desc struct.
 114  * This function will be called by the loader at startup. One would then
 115  * register each #GstPluginFeature.
 116  *
 117  * Returns: %TRUE if plugin initialised successfully
 118  */
 119 typedef gboolean (*GstPluginInitFunc) (GstPlugin *plugin);
 120
 121 /**
 122  * GstPluginInitFullFunc:
 123  * @plugin: The plugin object
 124  * @user_data: extra data
 125  *
 126  * A plugin should provide a pointer to a function of either #GstPluginInitFunc
 127  * or this type in the plugin_desc struct.
 128  * The function will be called by the loader at startup. One would then
 129  * register each #GstPluginFeature. This version allows
 130  * user data to be passed to init function (useful for bindings).
 131  *
 132  * Returns: %TRUE if plugin initialised successfully
 133  *
 134  * Since: 0.10.24
 135  *
 136  */
 137 typedef gboolean (*GstPluginInitFullFunc) (GstPlugin *plugin, gpointer user_data);
 138
 139 /**
 140  * GstPluginDesc:
 141  * @major_version: the major version number of core that plugin was compiled for
 142  * @minor_version: the minor version number of core that plugin was compiled for
 143  * @name: a unique name of the plugin
 144  * @description: description of plugin
 145  * @plugin_init: pointer to the init function of this plugin.
 146  * @version: version of the plugin
 147  * @license: effective license of plugin
 148  * @source: source module plugin belongs to
 149  * @package: shipped package plugin belongs to
 150  * @origin: URL to provider of plugin
 151  * @_gst_reserved: private, for later expansion
 152  *
 153  * A plugin should export a variable of this type called plugin_desc. The plugin
 154  * loader will use the data provided there to initialize the plugin.
 155  *
 156  * The @licence parameter must be one of: LGPL, GPL, QPL, GPL/QPL, MPL,
 157  * BSD, MIT/X11, Proprietary, unknown.
 158  */
 159 struct _GstPluginDesc {
 160   gint major_version;
 161   gint minor_version;
 162   const gchar *name;
 163   const gchar *description;
 164   GstPluginInitFunc plugin_init;
 165   const gchar *version;
 166   const gchar *license;
 167   const gchar *source;
 168   const gchar *package;
 169   const gchar *origin;
 170
 171   gpointer _gst_reserved[GST_PADDING];
 172 };
 173
 174
 175 #define GST_TYPE_PLUGIN   (gst_plugin_get_type())
 176 #define GST_IS_PLUGIN(obj)             (G_TYPE_CHECK_INSTANCE_TYPE ((obj), GST_TYPE_PLUGIN))
 177 #define GST_IS_PLUGIN_CLASS(klass)     (G_TYPE_CHECK_CLASS_TYPE ((klass), GST_TYPE_PLUGIN))
 178 #define GST_PLUGIN_GET_CLASS(obj)      (G_TYPE_INSTANCE_GET_CLASS ((obj), GST_TYPE_PLUGIN, GstPluginClass))
 179 #define GST_PLUGIN(obj)                (G_TYPE_CHECK_INSTANCE_CAST ((obj), GST_TYPE_PLUGIN, GstPlugin))
 180 #define GST_PLUGIN_CLASS(klass)        (G_TYPE_CHECK_CLASS_CAST ((klass), GST_TYPE_PLUGIN, GstPluginClass))
 181 #define GST_PLUGIN_CAST(obj)           ((GstPlugin*)(obj))
 182
 183 /**
 184  * GstPlugin:
 185  *
 186  * The plugin object
 187  */
 188 struct _GstPlugin {
 189   GstObject       object;
 190
 191   /*< private >*/
 192   GstPluginDesc desc;
 193
 194   GstPluginDesc *orig_desc;
 195
 196   unsigned int  flags;
 197
 198   gchar *       filename;
 199   gchar *       basename;       /* base name (non-dir part) of plugin path */
 200
 201   GModule *     module;         /* contains the module if plugin is loaded */
 202
 203   off_t         file_size;
 204   time_t        file_mtime;
 205   gboolean      registered;     /* TRUE when the registry has seen a filename
 206                                  * that matches the plugin's basename */
 207
 208   GstPluginPrivate *priv;
 209   gpointer _gst_reserved[GST_PADDING - 1];
 210 };
 211
 212 struct _GstPluginClass {
 213   GstObjectClass  object_class;
 214
 215   /*< private >*/
 216   gpointer _gst_reserved[GST_PADDING];
 217 };
 218
 219 /**
 220  * GST_PLUGIN_DEFINE:
 221  * @major: major version number of the gstreamer-core that plugin was compiled for
 222  * @minor: minor version number of the gstreamer-core that plugin was compiled for
 223  * @name: short, but unique name of the plugin
 224  * @description: information about the purpose of the plugin
 225  * @init: function pointer to the plugin_init method with the signature of <code>static gboolean plugin_init (GstPlugin * plugin)</code>.
 226  * @version: full version string (e.g. VERSION from config.h)
 227  * @license: under which licence the package has been released, e.g. GPL, LGPL.
 228  * @package: the package-name (e.g. PACKAGE_NAME from config.h)
 229  * @origin: a description from where the package comes from (e.g. the homepage URL)
 230  *
 231  * This macro needs to be used to define the entry point and meta data of a
 232  * plugin. One would use this macro to export a plugin, so that it can be used
 233  * by other applications.
 234  *
 235  * The macro uses a define named PACKAGE for the #GstPluginDesc,source field.
 236  */
 237 #define GST_PLUGIN_DEFINE(major,minor,name,description,init,version,license,package,origin)     \
 238 G_BEGIN_DECLS \
 239 GST_PLUGIN_EXPORT GstPluginDesc gst_plugin_desc = {     \
 240   major,                                                \
 241   minor,                                                \
 242   name,                                                 \
 243   (gchar *) description,                                \
 244   init,                                                 \
 245   version,                                              \
 246   license,                                              \
 247   PACKAGE,                                              \
 248   package,                                              \
 249   origin,                                               \
 250   GST_PADDING_INIT                                      \
 251 }; \
 252 G_END_DECLS
 253
 254 /**
 255  * GST_PLUGIN_DEFINE_STATIC:
 256  * @major: major version number of the gstreamer-core that plugin was compiled for
 257  * @minor: minor version number of the gstreamer-core that plugin was compiled for
 258  * @name: short, but unique name of the plugin
 259  * @description: information about the purpose of the plugin
 260  * @init: function pointer to the plugin_init method with the signature of <code>static gboolean plugin_init (GstPlugin * plugin)</code>.
 261  * @version: full version string (e.g. VERSION from config.h)
 262  * @license: under which licence the package has been released, e.g. GPL, LGPL.
 263  * @package: the package-name (e.g. PACKAGE_NAME from config.h)
 264  * @origin: a description from where the package comes from (e.g. the homepage URL)
 265  *
 266  * This macro needs to be used to define the entry point and meta data of a
 267  * local plugin. One would use this macro to define a local plugin that can only
 268  * be used by the own application.
 269  *
 270  * The macro uses a define named PACKAGE for the #GstPluginDesc.source field.
 271  *
 272  * Deprecated: Use gst_plugin_register_static() instead. This macro was
 273  * deprecated because it uses constructors, which is a compiler feature not
 274  * available on all compilers.
 275  *
 276  */
 277 /* We don't have deprecation guards here on purpose, it's enough to have
 278  * deprecation guards around _gst_plugin_register_static(), and will result in
 279  * much better error messages when compiling with -DGST_DISABLE_DEPRECATED */
 280 #define GST_PLUGIN_DEFINE_STATIC(major,minor,name,description,init,version,license,package,origin)  \
 281 static void GST_GNUC_CONSTRUCTOR                        \
 282 _gst_plugin_static_init__ ##init (void)                 \
 283 {                                                       \
 284   static GstPluginDesc plugin_desc_ = {                 \
 285     major,                                              \
 286     minor,                                              \
 287     name,                                               \
 288     (gchar *) description,                              \
 289     init,                                               \
 290     version,                                            \
 291     license,                                            \
 292     PACKAGE,                                            \
 293     package,                                            \
 294     origin,                                             \
 295     GST_PADDING_INIT                                    \
 296   };                                                    \
 297   _gst_plugin_register_static (&plugin_desc_);          \
 298 }
 299
 300 /**
 301  * GST_LICENSE_UNKNOWN:
 302  *
 303  * To be used in GST_PLUGIN_DEFINE or GST_PLUGIN_DEFINE_STATIC if usure about
 304  * the licence.
 305  */
 306 #define GST_LICENSE_UNKNOWN "unknown"
 307
 308
 309 /* function for filters */
 310 /**
 311  * GstPluginFilter:
 312  * @plugin: the plugin to check
 313  * @user_data: the user_data that has been passed on e.g. gst_registry_plugin_filter()
 314  *
 315  * A function that can be used with e.g. gst_registry_plugin_filter()
 316  * to get a list of plugins that match certain criteria.
 317  *
 318  * Returns: TRUE for a positive match, FALSE otherwise
 319  */
 320 typedef gboolean        (*GstPluginFilter)              (GstPlugin *plugin,
 321                                                          gpointer user_data);
 322
 323 GType                   gst_plugin_get_type             (void);
 324
 325 #ifndef GST_DISABLE_DEPRECATED
 326 void                    _gst_plugin_register_static     (GstPluginDesc *desc);
 327 #endif
 328
 329 gboolean                gst_plugin_register_static      (gint major_version,
 330                                                          gint minor_version,
 331                                                          const gchar *name,
 332                                                          const gchar *description,
 333                                                          GstPluginInitFunc init_func,
 334                                                          const gchar *version,
 335                                                          const gchar *license,
 336                                                          const gchar *source,
 337                                                          const gchar *package,
 338                                                          const gchar *origin);
 339
 340 gboolean                gst_plugin_register_static_full (gint major_version,
 341                                                          gint minor_version,
 342                                                          const gchar *name,
 343                                                          const gchar *description,
 344                                                          GstPluginInitFullFunc init_full_func,
 345                                                          const gchar *version,
 346                                                          const gchar *license,
 347                                                          const gchar *source,
 348                                                          const gchar *package,
 349                                                          const gchar *origin,
 350                                                          gpointer user_data);
 351
 352 G_CONST_RETURN gchar*   gst_plugin_get_name             (GstPlugin *plugin);
 353 G_CONST_RETURN gchar*   gst_plugin_get_description      (GstPlugin *plugin);
 354 G_CONST_RETURN gchar*   gst_plugin_get_filename         (GstPlugin *plugin);
 355 G_CONST_RETURN gchar*   gst_plugin_get_version          (GstPlugin *plugin);
 356 G_CONST_RETURN gchar*   gst_plugin_get_license          (GstPlugin *plugin);
 357 G_CONST_RETURN gchar*   gst_plugin_get_source           (GstPlugin *plugin);
 358 G_CONST_RETURN gchar*   gst_plugin_get_package          (GstPlugin *plugin);
 359 G_CONST_RETURN gchar*   gst_plugin_get_origin           (GstPlugin *plugin);
 360 G_CONST_RETURN GstStructure*    gst_plugin_get_cache_data       (GstPlugin * plugin);
 361 void            gst_plugin_set_cache_data       (GstPlugin * plugin, GstStructure *cache_data);
 362
 363 GModule *               gst_plugin_get_module           (GstPlugin *plugin);
 364 gboolean                gst_plugin_is_loaded            (GstPlugin *plugin);
 365
 366 gboolean                gst_plugin_name_filter          (GstPlugin *plugin, const gchar *name);
 367
 368 GstPlugin *             gst_plugin_load_file            (const gchar *filename, GError** error);
 369
 370 GstPlugin *             gst_plugin_load                 (GstPlugin *plugin);
 371 GstPlugin *             gst_plugin_load_by_name         (const gchar *name);
 372
 373 void                    gst_plugin_add_dependency (GstPlugin    * plugin,
 374                                                    const gchar ** env_vars,
 375                                                    const gchar ** paths,
 376                                                    const gchar ** names,
 377                                                    GstPluginDependencyFlags flags);
 378
 379 void                    gst_plugin_add_dependency_simple (GstPlugin   * plugin,
 380                                                           const gchar * env_vars,
 381                                                           const gchar * paths,
 382                                                           const gchar * names,
 383                                                           GstPluginDependencyFlags flags);
 384
 385 void gst_plugin_list_free (GList *list);
 386
 387 G_END_DECLS
 388
 389 #endif /* __GST_PLUGIN_H__ */