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 _GstPluginDesc GstPluginDesc;
  41
  42 /**
  43  * gst_plugin_error_quark:
  44  *
  45  * Get the error quark.
  46  *
  47  * Returns: The error quark used in GError messages
  48  */
  49 GQuark gst_plugin_error_quark (void);
  50 /**
  51  * GST_PLUGIN_ERROR:
  52  *
  53  * The error message category quark
  54  */
  55 #define GST_PLUGIN_ERROR gst_plugin_error_quark ()
  56
  57 /**
  58  * GstPluginError:
  59  * @GST_PLUGIN_ERROR_MODULE: The plugin could not be loaded
  60  * @GST_PLUGIN_ERROR_DEPENDENCIES: The plugin has unresolved dependencies
  61  * @GST_PLUGIN_ERROR_NAME_MISMATCH: The plugin has already be loaded from a different file
  62  *
  63  * The plugin loading errors
  64  */
  65 typedef enum
  66 {
  67   GST_PLUGIN_ERROR_MODULE,
  68   GST_PLUGIN_ERROR_DEPENDENCIES,
  69   GST_PLUGIN_ERROR_NAME_MISMATCH
  70 } GstPluginError;
  71
  72
  73 typedef enum
  74 {
  75   GST_PLUGIN_FLAG_CACHED = (1<<0),
  76 } GstPluginFlags;
  77
  78 /**
  79  * GstPluginInitFunc:
  80  * @plugin: The plugin object that can be used to register #GstPluginFeatures for this plugin.
  81  *
  82  * A plugin should provide a pointer to a function of this type in the
  83  * plugin_desc struct.
  84  * This function will be called by the loader at startup.
  85  *
  86  * Returns: %TRUE if plugin initialised successfully
  87  */
  88 typedef gboolean (*GstPluginInitFunc) (GstPlugin *plugin);
  89
  90 /**
  91  * GstPluginDesc:
  92  * @major_version: the major version number of core that plugin was compiled for
  93  * @minor_version: the minor version number of core that plugin was compiled for
  94  * @name: a unique name of the plugin
  95  * @description: description of plugin
  96  * @plugin_init: pointer to the init function of this plugin.
  97  * @version: version of the plugin
  98  * @license: effective license of plugin
  99  * @source: source module plugin belongs to
 100  * @package: shipped package plugin belongs to
 101  * @origin: URL to provider of plugin
 102  * @_gst_reserved: private, for later expansion
 103  *
 104  *
 105  * A plugins should export a variable of this type called plugin_desc. This plugin
 106  * loaded will use this variable to initialize the plugin.
 107  */
 108 struct _GstPluginDesc {
 109   gint major_version;
 110   gint minor_version;
 111   gchar *name;
 112   gchar *description;
 113   GstPluginInitFunc plugin_init;
 114   gchar *version;
 115   gchar *license;
 116   gchar *source;
 117   gchar *package;
 118   gchar *origin;
 119
 120   gpointer _gst_reserved[GST_PADDING];
 121 };
 122
 123
 124 #define GST_TYPE_PLUGIN   (gst_plugin_get_type())
 125 #define GST_IS_PLUGIN(obj)             (G_TYPE_CHECK_INSTANCE_TYPE ((obj), GST_TYPE_PLUGIN))
 126 #define GST_IS_PLUGIN_CLASS(klass)     (G_TYPE_CHECK_CLASS_TYPE ((klass), GST_TYPE_PLUGIN))
 127 #define GST_PLUGIN_GET_CLASS(obj)      (G_TYPE_INSTANCE_GET_CLASS ((obj), GST_TYPE_PLUGIN, GstPluginClass))
 128 #define GST_PLUGIN(obj)                (G_TYPE_CHECK_INSTANCE_CAST ((obj), GST_TYPE_PLUGIN, GstPlugin))
 129 #define GST_PLUGIN_CLASS(klass)        (G_TYPE_CHECK_CLASS_CAST ((klass), GST_TYPE_PLUGIN, GstPluginClass))
 130 #define GST_PLUGIN_CAST(obj)           ((GstPlugin*)(obj))
 131
 132 /**
 133  * GstPlugin:
 134  *
 135  * The plugin object
 136  */
 137 struct _GstPlugin {
 138   GstObject       object;
 139
 140   /*< private >*/
 141   GstPluginDesc desc;
 142
 143   GstPluginDesc *orig_desc;
 144
 145   unsigned int  flags;
 146
 147   gchar *       filename;
 148   gchar *       basename;       /* base name (non-dir part) of plugin path */
 149
 150   GModule *     module;         /* contains the module if plugin is loaded */
 151
 152   off_t         file_size;
 153   time_t        file_mtime;
 154   gboolean      registered;     /* TRUE when the registry has seen a filename
 155                                  * that matches the plugin's basename */
 156
 157   gpointer _gst_reserved[GST_PADDING];
 158 };
 159
 160 struct _GstPluginClass {
 161   GstObjectClass  object_class;
 162
 163   /*< private >*/
 164   gpointer _gst_reserved[GST_PADDING];
 165 };
 166
 167 /**
 168  * GST_PLUGIN_DEFINE:
 169  * @major: major version number of the gstreamer-core that plugin was compiled for
 170  * @minor: minor version number of the gstreamer-core that plugin was compiled for
 171  * @name: short, but unique name of the plugin
 172  * @description: information about the purpose of the plugin
 173  * @init: function pointer to the plugin_init method with the signature of <code>static gboolean plugin_init (GstPlugin * plugin)</code>.
 174  * @version: full version string (e.g. VERSION from config.h)
 175  * @license: under which licence the package has been released, e.g. GPL, LGPL.
 176  * @package: the package-name (e.g. PACKAGE_NAME from config.h)
 177  * @origin: a description from where the package comes from (e.g. the homepage URL)
 178  *
 179  * This macro needs to be used to define the entry point and meta data of a
 180  * plugin. One would use this macro to export a plugin, so that it can be used
 181  * by other applications
 182  */
 183 #define GST_PLUGIN_DEFINE(major,minor,name,description,init,version,license,package,origin)     \
 184 GST_PLUGIN_EXPORT GstPluginDesc gst_plugin_desc = {     \
 185   major,                                                \
 186   minor,                                                \
 187   name,                                                 \
 188   description,                                          \
 189   init,                                                 \
 190   version,                                              \
 191   license,                                              \
 192   PACKAGE,                                              \
 193   package,                                              \
 194   origin,                                               \
 195   GST_PADDING_INIT                                      \
 196 };
 197
 198 /**
 199  * GST_PLUGIN_DEFINE_STATIC:
 200  * @major: major version number of the gstreamer-core that plugin was compiled for
 201  * @minor: minor version number of the gstreamer-core that plugin was compiled for
 202  * @name: short, but unique name of the plugin
 203  * @description: information about the purpose of the plugin
 204  * @init: function pointer to the plugin_init method with the signature of <code>static gboolean plugin_init (GstPlugin * plugin)</code>.
 205  * @version: full version string (e.g. VERSION from config.h)
 206  * @license: under which licence the package has been released, e.g. GPL, LGPL.
 207  * @package: the package-name (e.g. PACKAGE_NAME from config.h)
 208  * @origin: a description from where the package comes from (e.g. the homepage URL)
 209  *
 210  * This macro needs to be used to define the entry point and meta data of a
 211  * local plugin. One would use this macro to define a local plugin that can only
 212  * be used by the own application.
 213  */
 214 #define GST_PLUGIN_DEFINE_STATIC(major,minor,name,description,init,version,license,package,origin)  \
 215 static void GST_GNUC_CONSTRUCTOR                        \
 216 _gst_plugin_static_init__ ##init (void)                 \
 217 {                                                       \
 218   static GstPluginDesc plugin_desc_ = {                 \
 219     major,                                              \
 220     minor,                                              \
 221     name,                                               \
 222     description,                                        \
 223     init,                                               \
 224     version,                                            \
 225     license,                                            \
 226     PACKAGE,                                            \
 227     package,                                            \
 228     origin,                                             \
 229     GST_PADDING_INIT                                    \
 230   };                                                    \
 231   _gst_plugin_register_static (&plugin_desc_);          \
 232 }
 233
 234 /**
 235  * GST_LICENSE_UNKNOWN:
 236  *
 237  * To be used in GST_PLUGIN_DEFINE or GST_PLUGIN_DEFINE_STATIC if usure about
 238  * the licence.
 239  */
 240 #define GST_LICENSE_UNKNOWN "unknown"
 241
 242
 243 /* function for filters */
 244 /**
 245  * GstPluginFilter:
 246  * @plugin: the plugin to check
 247  * @user_data: the user_data that has been passed on e.g. gst_registry_plugin_filter()
 248  *
 249  * A function that can be used with e.g. gst_registry_plugin_filter()
 250  * to get a list of plugins that match certain criteria.
 251  *
 252  * Returns: TRUE for a positive match, FALSE otherwise
 253  */
 254 typedef gboolean        (*GstPluginFilter)              (GstPlugin *plugin,
 255                                                          gpointer user_data);
 256
 257 GType                   gst_plugin_get_type             (void);
 258
 259 void                    _gst_plugin_initialize          (void);
 260 void                    _gst_plugin_register_static     (GstPluginDesc *desc);
 261
 262 G_CONST_RETURN gchar*   gst_plugin_get_name             (GstPlugin *plugin);
 263 G_CONST_RETURN gchar*   gst_plugin_get_description      (GstPlugin *plugin);
 264 G_CONST_RETURN gchar*   gst_plugin_get_filename         (GstPlugin *plugin);
 265 G_CONST_RETURN gchar*   gst_plugin_get_version          (GstPlugin *plugin);
 266 G_CONST_RETURN gchar*   gst_plugin_get_license          (GstPlugin *plugin);
 267 G_CONST_RETURN gchar*   gst_plugin_get_source           (GstPlugin *plugin);
 268 G_CONST_RETURN gchar*   gst_plugin_get_package          (GstPlugin *plugin);
 269 G_CONST_RETURN gchar*   gst_plugin_get_origin           (GstPlugin *plugin);
 270 GModule *               gst_plugin_get_module           (GstPlugin *plugin);
 271 gboolean                gst_plugin_is_loaded            (GstPlugin *plugin);
 272
 273 gboolean                gst_plugin_name_filter          (GstPlugin *plugin, const gchar *name);
 274
 275 GstPlugin *             gst_plugin_load_file            (const gchar *filename, GError** error);
 276
 277 GstPlugin *             gst_plugin_load                 (GstPlugin *plugin);
 278 GstPlugin *             gst_plugin_load_by_name         (const gchar *name);
 279
 280 void gst_plugin_list_free (GList *list);
 281
 282 G_END_DECLS
 283
 284 #endif /* __GST_PLUGIN_H__ */