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