gstplugin.h 15.2 KB
Newer Older
1 2 3 4 5
/* GStreamer
 * Copyright (C) 1999,2000 Erik Walthinsen <omega@cse.ogi.edu>
 *                    2000 Wim Taymans <wtay@chello.be>
 *
 * gstplugin.h: Header for plugin subsystem
Erik Walthinsen's avatar
Erik Walthinsen committed
6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26
 *
 * This library is free software; you can redistribute it and/or
 * modify it under the terms of the GNU Library General Public
 * License as published by the Free Software Foundation; either
 * version 2 of the License, or (at your option) any later version.
 *
 * This library is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 * Library General Public License for more details.
 *
 * You should have received a copy of the GNU Library General Public
 * License along with this library; if not, write to the
 * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
 * Boston, MA 02111-1307, USA.
 */


#ifndef __GST_PLUGIN_H__
#define __GST_PLUGIN_H__

27
#include <gst/gstconfig.h>
Erik Walthinsen's avatar
Erik Walthinsen committed
28

Thomas Vander Stichele's avatar
Thomas Vander Stichele committed
29
#include <time.h> /* time_t */
Thomas Vander Stichele's avatar
Thomas Vander Stichele committed
30
#include <sys/types.h> /* off_t */
Thomas Vander Stichele's avatar
Thomas Vander Stichele committed
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

David Schleef's avatar
remove  
David Schleef committed
39 40
typedef struct _GstPlugin GstPlugin;
typedef struct _GstPluginClass GstPluginClass;
41
typedef struct _GstPluginPrivate GstPluginPrivate;
David Schleef's avatar
remove  
David Schleef committed
42 43
typedef struct _GstPluginDesc GstPluginDesc;

44 45 46 47 48 49 50
/**
 * gst_plugin_error_quark:
 *
 * Get the error quark.
 *
 * Returns: The error quark used in GError messages
 */
51
GQuark gst_plugin_error_quark (void);
52 53 54 55 56
/**
 * GST_PLUGIN_ERROR:
 *
 * The error message category quark
 */
57 58
#define GST_PLUGIN_ERROR gst_plugin_error_quark ()

59 60 61 62 63 64 65 66
/**
 * GstPluginError:
 * @GST_PLUGIN_ERROR_MODULE: The plugin could not be loaded
 * @GST_PLUGIN_ERROR_DEPENDENCIES: The plugin has unresolved dependencies
 * @GST_PLUGIN_ERROR_NAME_MISMATCH: The plugin has already be loaded from a different file
 *
 * The plugin loading errors
 */
67 68 69
typedef enum
{
  GST_PLUGIN_ERROR_MODULE,
70 71
  GST_PLUGIN_ERROR_DEPENDENCIES,
  GST_PLUGIN_ERROR_NAME_MISMATCH
72
} GstPluginError;
73

74 75 76 77 78 79 80
/**
 * GstPluginFlags:
 * @GST_PLUGIN_FLAG_CACHED: Temporarily loaded plugins
 * @GST_PLUGIN_FLAG_BLACKLISTED: The plugin won't be scanned (again)
 *
 * The plugin loading state
 */
David Schleef's avatar
remove  
David Schleef committed
81 82
typedef enum
{
83 84
  GST_PLUGIN_FLAG_CACHED = (1<<0),
  GST_PLUGIN_FLAG_BLACKLISTED = (1<<1)
David Schleef's avatar
remove  
David Schleef committed
85
} GstPluginFlags;
Erik Walthinsen's avatar
Erik Walthinsen committed
86

87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107
/**
 * GstPluginDependencyFlags:
 * @GST_PLUGIN_DEPENDENCY_FLAG_NONE : no special flags
 * @GST_PLUGIN_DEPENDENCY_FLAG_RECURSE : recurse into subdirectories
 * @GST_PLUGIN_DEPENDENCY_FLAG_PATHS_ARE_DEFAULT_ONLY : use paths
 *         argument only if none of the environment variables is set
 * @GST_PLUGIN_DEPENDENCY_FLAG_FILE_NAME_IS_SUFFIX : interpret
 *         filename argument as filter suffix and check all matching files in
 *         the directory
 *
 * Flags used in connection with gst_plugin_add_dependency().
 *
 * Since: 0.10.22
 */
typedef enum {
  GST_PLUGIN_DEPENDENCY_FLAG_NONE = 0,
  GST_PLUGIN_DEPENDENCY_FLAG_RECURSE = (1 << 0),
  GST_PLUGIN_DEPENDENCY_FLAG_PATHS_ARE_DEFAULT_ONLY = (1 << 1),
  GST_PLUGIN_DEPENDENCY_FLAG_FILE_NAME_IS_SUFFIX = (1 << 2)
} GstPluginDependencyFlags;

108 109
/**
 * GstPluginInitFunc:
Stefan Kost's avatar
Stefan Kost committed
110
 * @plugin: The plugin object
111 112 113
 *
 * A plugin should provide a pointer to a function of this type in the
 * plugin_desc struct.
Stefan Kost's avatar
Stefan Kost committed
114 115
 * This function will be called by the loader at startup. One would then
 * register each #GstPluginFeature.
116
 *
Thomas Vander Stichele's avatar
Thomas Vander Stichele committed
117
 * Returns: %TRUE if plugin initialised successfully
118
 */
119
/* FIXME 0.11: Make return void */
120
typedef gboolean (*GstPluginInitFunc) (GstPlugin *plugin);
121

122 123
/**
 * GstPluginInitFullFunc:
Stefan Kost's avatar
Stefan Kost committed
124
 * @plugin: The plugin object
Stefan Kost's avatar
Stefan Kost committed
125
 * @user_data: extra data
126 127 128
 *
 * A plugin should provide a pointer to a function of either #GstPluginInitFunc
 * or this type in the plugin_desc struct.
Stefan Kost's avatar
Stefan Kost committed
129 130
 * The function will be called by the loader at startup. One would then
 * register each #GstPluginFeature. This version allows
131 132 133 134 135 136 137
 * user data to be passed to init function (useful for bindings).
 *
 * Returns: %TRUE if plugin initialised successfully
 *
 * Since: 0.10.24
 *
 */
138
/* FIXME 0.11: Merge with GstPluginInitFunc */
139 140
typedef gboolean (*GstPluginInitFullFunc) (GstPlugin *plugin, gpointer user_data);

141 142 143 144 145 146 147 148 149 150 151 152
/**
 * GstPluginDesc:
 * @major_version: the major version number of core that plugin was compiled for
 * @minor_version: the minor version number of core that plugin was compiled for
 * @name: a unique name of the plugin
 * @description: description of plugin
 * @plugin_init: pointer to the init function of this plugin.
 * @version: version of the plugin
 * @license: effective license of plugin
 * @source: source module plugin belongs to
 * @package: shipped package plugin belongs to
 * @origin: URL to provider of plugin
153 154 155 156 157
 * @release_datetime: date time string in ISO 8601 format (or rather, a
 *     subset thereof), or NULL. Allowed are the following formats:
 *     "YYYY-MM-DD" and "YYY-MM-DDTHH:MMZ" (with 'T' a separator and 'Z'
 *     indicating UTC/Zulu time). This field should be set via the
 *     GST_PACKAGE_RELEASE_DATETIME preprocessor macro (Since: 0.10.31)
Thomas Vander Stichele's avatar
Thomas Vander Stichele committed
158
 *
159 160
 * A plugin should export a variable of this type called plugin_desc. The plugin
 * loader will use the data provided there to initialize the plugin.
161
 *
162
 * The @licence parameter must be one of: LGPL, GPL, QPL, GPL/QPL, MPL,
163
 * BSD, MIT/X11, Proprietary, unknown.
164
 */
165
struct _GstPluginDesc {
166 167
  gint major_version;
  gint minor_version;
168
  const gchar *name;
Benjamin Otte's avatar
Benjamin Otte committed
169
  const gchar *description;
170
  GstPluginInitFunc plugin_init;
171 172 173 174 175
  const gchar *version;
  const gchar *license;
  const gchar *source;
  const gchar *package;
  const gchar *origin;
176 177 178
  const gchar *release_datetime;
  /*< private >*/
  gpointer _gst_reserved[GST_PADDING - 1];
Erik Walthinsen's avatar
Erik Walthinsen committed
179 180
};

David Schleef's avatar
remove  
David Schleef committed
181 182 183 184 185 186 187

#define GST_TYPE_PLUGIN   (gst_plugin_get_type())
#define GST_IS_PLUGIN(obj)             (G_TYPE_CHECK_INSTANCE_TYPE ((obj), GST_TYPE_PLUGIN))
#define GST_IS_PLUGIN_CLASS(klass)     (G_TYPE_CHECK_CLASS_TYPE ((klass), GST_TYPE_PLUGIN))
#define GST_PLUGIN_GET_CLASS(obj)      (G_TYPE_INSTANCE_GET_CLASS ((obj), GST_TYPE_PLUGIN, GstPluginClass))
#define GST_PLUGIN(obj)                (G_TYPE_CHECK_INSTANCE_CAST ((obj), GST_TYPE_PLUGIN, GstPlugin))
#define GST_PLUGIN_CLASS(klass)        (G_TYPE_CHECK_CLASS_CAST ((klass), GST_TYPE_PLUGIN, GstPluginClass))
188
#define GST_PLUGIN_CAST(obj)           ((GstPlugin*)(obj))
David Schleef's avatar
remove  
David Schleef committed
189

190 191 192 193 194
/**
 * GstPlugin:
 *
 * The plugin object
 */
195
struct _GstPlugin {
196
  GstObject       object;
David Schleef's avatar
remove  
David Schleef committed
197

198
  /*< private >*/
199
  GstPluginDesc	desc;
Erik Walthinsen's avatar
Erik Walthinsen committed
200

David Schleef's avatar
remove  
David Schleef committed
201 202 203 204
  GstPluginDesc *orig_desc;

  unsigned int  flags;

205
  gchar *	filename;
206
  gchar *	basename;       /* base name (non-dir part) of plugin path */
207

208
  GModule *	module;		/* contains the module if plugin is loaded */
209

Thomas Vander Stichele's avatar
Thomas Vander Stichele committed
210
  off_t         file_size;
David Schleef's avatar
remove  
David Schleef committed
211
  time_t        file_mtime;
212 213
  gboolean      registered;     /* TRUE when the registry has seen a filename
                                 * that matches the plugin's basename */
David Schleef's avatar
remove  
David Schleef committed
214

215 216
  GstPluginPrivate *priv;
  gpointer _gst_reserved[GST_PADDING - 1];
217
};
Erik Walthinsen's avatar
Erik Walthinsen committed
218

David Schleef's avatar
remove  
David Schleef committed
219
struct _GstPluginClass {
220
  GstObjectClass  object_class;
David Schleef's avatar
remove  
David Schleef committed
221

222
  /*< private >*/
223
  gpointer _gst_reserved[GST_PADDING];
David Schleef's avatar
remove  
David Schleef committed
224 225
};

226 227 228 229 230 231
#ifdef GST_PACKAGE_RELEASE_DATETIME
#define __GST_PACKAGE_RELEASE_DATETIME GST_PACKAGE_RELEASE_DATETIME
#else
#define __GST_PACKAGE_RELEASE_DATETIME NULL
#endif

232 233 234 235 236 237 238 239 240 241 242 243 244 245
/**
 * GST_PLUGIN_DEFINE:
 * @major: major version number of the gstreamer-core that plugin was compiled for
 * @minor: minor version number of the gstreamer-core that plugin was compiled for
 * @name: short, but unique name of the plugin
 * @description: information about the purpose of the plugin
 * @init: function pointer to the plugin_init method with the signature of <code>static gboolean plugin_init (GstPlugin * plugin)</code>.
 * @version: full version string (e.g. VERSION from config.h)
 * @license: under which licence the package has been released, e.g. GPL, LGPL.
 * @package: the package-name (e.g. PACKAGE_NAME from config.h)
 * @origin: a description from where the package comes from (e.g. the homepage URL)
 *
 * This macro needs to be used to define the entry point and meta data of a
 * plugin. One would use this macro to export a plugin, so that it can be used
246 247 248
 * by other applications.
 *
 * The macro uses a define named PACKAGE for the #GstPluginDesc,source field.
249 250 251 252 253 254 255
 * When using autoconf, this is usually set automatically via the AC_INIT
 * macro, and set in config.h. If you are not using autoconf, you will need to
 * define PACKAGE yourself and set it to a short mnemonic string identifying
 * your application/package, e.g. 'someapp' or 'my-plugins-foo.
 *
 * If defined, the GST_PACKAGE_RELEASE_DATETIME will also be used for the
 * #GstPluginDesc,release_datetime field.
256
 */
David Schleef's avatar
David Schleef committed
257
#define GST_PLUGIN_DEFINE(major,minor,name,description,init,version,license,package,origin)	\
258
G_BEGIN_DECLS \
259
GST_PLUGIN_EXPORT GstPluginDesc gst_plugin_desc = {	\
260 261 262
  major,						\
  minor,						\
  name,							\
263
  (gchar *) description,				\
264 265
  init,							\
  version,						\
266
  license,						\
267
  PACKAGE,						\
268 269
  package,						\
  origin,						\
270
  __GST_PACKAGE_RELEASE_DATETIME,                       \
David Schleef's avatar
David Schleef committed
271
  GST_PADDING_INIT				        \
272 273
}; \
G_END_DECLS
David Schleef's avatar
David Schleef committed
274

275 276 277 278 279 280 281 282 283 284 285 286 287 288 289
/**
 * GST_PLUGIN_DEFINE_STATIC:
 * @major: major version number of the gstreamer-core that plugin was compiled for
 * @minor: minor version number of the gstreamer-core that plugin was compiled for
 * @name: short, but unique name of the plugin
 * @description: information about the purpose of the plugin
 * @init: function pointer to the plugin_init method with the signature of <code>static gboolean plugin_init (GstPlugin * plugin)</code>.
 * @version: full version string (e.g. VERSION from config.h)
 * @license: under which licence the package has been released, e.g. GPL, LGPL.
 * @package: the package-name (e.g. PACKAGE_NAME from config.h)
 * @origin: a description from where the package comes from (e.g. the homepage URL)
 *
 * This macro needs to be used to define the entry point and meta data of a
 * local plugin. One would use this macro to define a local plugin that can only
 * be used by the own application.
290
 *
291 292
 * The macro uses a define named PACKAGE for the #GstPluginDesc.source field.
 *
293 294 295
 * Deprecated: Use gst_plugin_register_static() instead. This macro was
 * deprecated because it uses constructors, which is a compiler feature not
 * available on all compilers.
296
 *
297
 */
298 299 300
/* We don't have deprecation guards here on purpose, it's enough to have
 * deprecation guards around _gst_plugin_register_static(), and will result in
 * much better error messages when compiling with -DGST_DISABLE_DEPRECATED */
301
#define GST_PLUGIN_DEFINE_STATIC(major,minor,name,description,init,version,license,package,origin)  \
302 303
static void GST_GNUC_CONSTRUCTOR			\
_gst_plugin_static_init__ ##init (void)			\
304 305 306 307
{							\
  static GstPluginDesc plugin_desc_ = {			\
    major,						\
    minor,						\
308
    name,						\
309
    (gchar *) description,				\
310
    init,						\
311
    version,						\
312
    license,						\
313
    PACKAGE,						\
314 315
    package,						\
    origin,						\
316
    NULL,						\
317
    GST_PADDING_INIT				        \
318 319
  };							\
  _gst_plugin_register_static (&plugin_desc_);		\
320
}
321

322 323 324 325 326 327
/**
 * GST_LICENSE_UNKNOWN:
 *
 * To be used in GST_PLUGIN_DEFINE or GST_PLUGIN_DEFINE_STATIC if usure about
 * the licence.
 */
328
#define GST_LICENSE_UNKNOWN "unknown"
329

330

331
/* function for filters */
332 333 334 335 336 337 338 339 340 341
/**
 * GstPluginFilter:
 * @plugin: the plugin to check
 * @user_data: the user_data that has been passed on e.g. gst_registry_plugin_filter()
 *
 * A function that can be used with e.g. gst_registry_plugin_filter()
 * to get a list of plugins that match certain criteria.
 *
 * Returns: TRUE for a positive match, FALSE otherwise
 */
342 343
typedef gboolean        (*GstPluginFilter)              (GstPlugin *plugin,
                                                         gpointer user_data);
344

345
GType                   gst_plugin_get_type             (void);
David Schleef's avatar
remove  
David Schleef committed
346

347
#ifndef GST_DISABLE_DEPRECATED
348
void			_gst_plugin_register_static	(GstPluginDesc *desc);
349 350
#endif

351 352 353
gboolean		gst_plugin_register_static	(gint major_version,
                                                         gint minor_version,
                                                         const gchar *name,
Benjamin Otte's avatar
Benjamin Otte committed
354
                                                         const gchar *description,
355 356 357 358 359 360
                                                         GstPluginInitFunc init_func,
                                                         const gchar *version,
                                                         const gchar *license,
                                                         const gchar *source,
                                                         const gchar *package,
                                                         const gchar *origin);
361

362 363 364
gboolean		gst_plugin_register_static_full	(gint major_version,
                                                         gint minor_version,
                                                         const gchar *name,
Benjamin Otte's avatar
Benjamin Otte committed
365
                                                         const gchar *description,
366 367 368 369 370 371 372 373
                                                         GstPluginInitFullFunc init_full_func,
                                                         const gchar *version,
                                                         const gchar *license,
                                                         const gchar *source,
                                                         const gchar *package,
                                                         const gchar *origin,
                                                         gpointer user_data);

374 375 376 377 378 379 380 381 382 383
const gchar*		gst_plugin_get_name		(GstPlugin *plugin);
const gchar*		gst_plugin_get_description	(GstPlugin *plugin);
const gchar*		gst_plugin_get_filename		(GstPlugin *plugin);
const gchar*		gst_plugin_get_version		(GstPlugin *plugin);
const gchar*		gst_plugin_get_license		(GstPlugin *plugin);
const gchar*		gst_plugin_get_source		(GstPlugin *plugin);
const gchar*		gst_plugin_get_package		(GstPlugin *plugin);
const gchar*		gst_plugin_get_origin		(GstPlugin *plugin);
const GstStructure*	gst_plugin_get_cache_data	(GstPlugin * plugin);
void			gst_plugin_set_cache_data	(GstPlugin * plugin, GstStructure *cache_data);
384

385 386 387 388 389
GModule *		gst_plugin_get_module		(GstPlugin *plugin);
gboolean		gst_plugin_is_loaded		(GstPlugin *plugin);

gboolean		gst_plugin_name_filter		(GstPlugin *plugin, const gchar *name);

390
GstPlugin *		gst_plugin_load_file		(const gchar *filename, GError** error);
391

David Schleef's avatar
remove  
David Schleef committed
392
GstPlugin *             gst_plugin_load                 (GstPlugin *plugin);
393
GstPlugin *             gst_plugin_load_by_name         (const gchar *name);
David Schleef's avatar
remove  
David Schleef committed
394

395 396 397 398 399 400 401 402 403 404 405 406
void                    gst_plugin_add_dependency (GstPlugin    * plugin,
                                                   const gchar ** env_vars,
                                                   const gchar ** paths,
                                                   const gchar ** names,
                                                   GstPluginDependencyFlags flags);

void                    gst_plugin_add_dependency_simple (GstPlugin   * plugin,
                                                          const gchar * env_vars,
                                                          const gchar * paths,
                                                          const gchar * names,
                                                          GstPluginDependencyFlags flags);

407
void gst_plugin_list_free (GList *list);
408

409
G_END_DECLS
410

Erik Walthinsen's avatar
Erik Walthinsen committed
411
#endif /* __GST_PLUGIN_H__ */