/* GStreamer

 * Copyright (C) 1999,2000 Erik Walthinsen <omega@cse.ogi.edu>

 *                    2000 Wim Taymans <wtay@chello.be>

 *

 * gstplugin.h: Header for plugin subsystem

 *

 * 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., 51 Franklin St, Fifth Floor,

 * Boston, MA 02110-1301, USA.

 */

#ifndef __GST_PLUGIN_H__

#define __GST_PLUGIN_H__

#include <gst/gstconfig.h>

#include <gst/gstobject.h>

#include <gst/gstmacros.h>

#include <gst/gststructure.h>

G_BEGIN_DECLS

/**

 * GstPlugin:

 *

 * The opaque plugin object

 */

typedef struct _GstPlugin GstPlugin;

typedef struct _GstPluginClass GstPluginClass;

typedef struct _GstPluginDesc GstPluginDesc;

/**

 * gst_plugin_error_quark:

 *

 * Get the error quark.

 *

 * Returns: The error quark used in GError messages

 */

GST_API

GQuark gst_plugin_error_quark (void);

/**

 * GST_PLUGIN_ERROR:

 *

 * The error message category quark

 */

#define GST_PLUGIN_ERROR gst_plugin_error_quark ()

/**

 * 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

 */

typedef enum

{

  GST_PLUGIN_ERROR_MODULE,

  GST_PLUGIN_ERROR_DEPENDENCIES,

  GST_PLUGIN_ERROR_NAME_MISMATCH

} GstPluginError;

/**

 * GstPluginFlags:

 * @GST_PLUGIN_FLAG_CACHED: Temporarily loaded plugins

 * @GST_PLUGIN_FLAG_BLACKLISTED: The plugin won't be scanned (again)

 *

 * The plugin loading state

 */

typedef enum

{

  GST_PLUGIN_FLAG_CACHED      = (GST_OBJECT_FLAG_LAST << 0),

  GST_PLUGIN_FLAG_BLACKLISTED = (GST_OBJECT_FLAG_LAST << 1)

} GstPluginFlags;

/**

 * 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

 * @GST_PLUGIN_DEPENDENCY_FLAG_FILE_NAME_IS_PREFIX : interpret

 *         filename argument as filter prefix and check all matching files in

 *         the directory. Since 1.8.

 * @GST_PLUGIN_DEPENDENCY_FLAG_PATHS_ARE_RELATIVE_TO_EXE : interpret

 *   non-absolute paths as relative to the main executable directory. Since

 *   1.14.

 *

 * Flags used in connection with gst_plugin_add_dependency().

 */

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),

  GST_PLUGIN_DEPENDENCY_FLAG_FILE_NAME_IS_PREFIX = (1 << 3),

  GST_PLUGIN_DEPENDENCY_FLAG_PATHS_ARE_RELATIVE_TO_EXE = (1 << 4)

} GstPluginDependencyFlags;

/**

 * GstPluginInitFunc:

 * @plugin: The plugin object

 *

 * A plugin should provide a pointer to a function of this type in the

 * plugin_desc struct.

 * This function will be called by the loader at startup. One would then

 * register each #GstPluginFeature.

 *

 * Returns: %TRUE if plugin initialised successfully

 */

/* FIXME 0.11: Make return void */

typedef gboolean (*GstPluginInitFunc) (GstPlugin *plugin);

/**

 * GstPluginInitFullFunc:

 * @plugin: The plugin object

 * @user_data: extra data

 *

 * A plugin should provide a pointer to a function of either #GstPluginInitFunc

 * or this type in the plugin_desc struct.

 * The function will be called by the loader at startup. One would then

 * register each #GstPluginFeature. This version allows

 * user data to be passed to init function (useful for bindings).

 *

 * Returns: %TRUE if plugin initialised successfully

 */

/* FIXME 0.11: Merge with GstPluginInitFunc */

typedef gboolean (*GstPluginInitFullFunc) (GstPlugin *plugin, gpointer user_data);

/**

 * 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

 * @release_datetime: (allow-none): 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.

 *

 * 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.

 *

 * The @licence parameter must be one of: LGPL, GPL, QPL, GPL/QPL, MPL,

 * BSD, MIT/X11, Proprietary, unknown.

 */

struct _GstPluginDesc {

  gint major_version;

  gint minor_version;

  const gchar *name;

  const gchar *description;

  GstPluginInitFunc plugin_init;

  const gchar *version;

  const gchar *license;

  const gchar *source;

  const gchar *package;

  const gchar *origin;

  const gchar *release_datetime;

  /*< private >*/

  gpointer _gst_reserved[GST_PADDING];

};

#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))

#define GST_PLUGIN_CAST(obj)           ((GstPlugin*)(obj))

#ifdef GST_PACKAGE_RELEASE_DATETIME

#define __GST_PACKAGE_RELEASE_DATETIME GST_PACKAGE_RELEASE_DATETIME

#else

#define __GST_PACKAGE_RELEASE_DATETIME NULL

#endif

/**

 * GST_PLUGIN_STATIC_DECLARE:

 * @name: short, but unique name of the plugin

 *

 * This macro can be used to initialize statically linked plugins. It is

 * necessary to call this macro before the plugin can be used.

 * It has to be used in combination with GST_PLUGIN_STATIC_REGISTER

 * and must be placed outside any block to declare the plugin initialization

 * function.

 *

 * Since: 1.2

 */

#define GST_PLUGIN_STATIC_DECLARE(name) \

  extern void G_PASTE(gst_plugin_, G_PASTE(name, _register)) (void)

/**

 * GST_PLUGIN_STATIC_REGISTER:

 * @name: short, but unique name of the plugin

 *

 * This macro can be used to initialize statically linked plugins. It is

 * necessary to call this macro before the plugin can be used.

 * It has to be used in combination with GST_PLUGIN_STATIC_DECLARE and

 * calls the plugin initialization function.

 *

 * Since: 1.2

 */

#define GST_PLUGIN_STATIC_REGISTER(name) G_PASTE(gst_plugin_, G_PASTE(name, _register)) ()

/**

 * 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 static gboolean plugin_init (GstPlugin * plugin).

 * @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

 * by other applications.

 *

 * The macro uses a define named PACKAGE for the #GstPluginDesc,source field.

 * 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.

 */

#define GST_PLUGIN_DEFINE(major,minor,name,description,init,version,license,package,origin) \

G_BEGIN_DECLS \

GST_PLUGIN_EXPORT const GstPluginDesc * G_PASTE(gst_plugin_, G_PASTE(name, _get_desc)) (void); \

GST_PLUGIN_EXPORT void G_PASTE(gst_plugin_, G_PASTE(name, _register)) (void); \

\

static const GstPluginDesc gst_plugin_desc = { \

  major, \

  minor, \

  G_STRINGIFY(name), \

  (gchar *) description, \

  init, \

  version, \

  license, \

  PACKAGE, \

  package, \

  origin, \

  __GST_PACKAGE_RELEASE_DATETIME, \

  GST_PADDING_INIT \

};                                       \

\

const GstPluginDesc * \

G_PASTE(gst_plugin_, G_PASTE(name, _get_desc)) (void) \

{ \

    return &gst_plugin_desc; \

} \

\

void \

G_PASTE(gst_plugin_, G_PASTE(name, _register)) (void) \

{ \

  gst_plugin_register_static (major, minor, G_STRINGIFY(name), \

      description, init, version, license, \

      PACKAGE, package, origin); \

} \

G_END_DECLS

/**

 * GST_LICENSE_UNKNOWN:

 *

 * To be used in GST_PLUGIN_DEFINE if unsure about the licence.

 */

#define GST_LICENSE_UNKNOWN "unknown"

/* function for filters */

/**

 * 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

 */

typedef gboolean        (*GstPluginFilter)              (GstPlugin *plugin,

                                                         gpointer user_data);

GST_API

GType                   gst_plugin_get_type             (void);

GST_API

gboolean		gst_plugin_register_static	(gint major_version,

                                                         gint minor_version,

                                                         const gchar *name,

                                                         const gchar *description,

                                                         GstPluginInitFunc init_func,

                                                         const gchar *version,

                                                         const gchar *license,

                                                         const gchar *source,

                                                         const gchar *package,

                                                         const gchar *origin);

GST_API

gboolean		gst_plugin_register_static_full	(gint major_version,

                                                         gint minor_version,

                                                         const gchar *name,

                                                         const gchar *description,

                                                         GstPluginInitFullFunc init_full_func,

                                                         const gchar *version,

                                                         const gchar *license,

                                                         const gchar *source,

                                                         const gchar *package,

                                                         const gchar *origin,

                                                         gpointer user_data);

GST_API

const gchar*		gst_plugin_get_name		(GstPlugin *plugin);

GST_API

const gchar*		gst_plugin_get_description	(GstPlugin *plugin);

GST_API

const gchar*		gst_plugin_get_filename		(GstPlugin *plugin);

GST_API

const gchar*		gst_plugin_get_version		(GstPlugin *plugin);

GST_API

const gchar*		gst_plugin_get_license		(GstPlugin *plugin);

GST_API

const gchar*		gst_plugin_get_source		(GstPlugin *plugin);

GST_API

const gchar*		gst_plugin_get_package		(GstPlugin *plugin);

GST_API

const gchar*		gst_plugin_get_origin		(GstPlugin *plugin);

GST_API

const gchar*		gst_plugin_get_release_date_string (GstPlugin *plugin);

GST_API

const GstStructure*	gst_plugin_get_cache_data	(GstPlugin * plugin);

GST_API

void			gst_plugin_set_cache_data	(GstPlugin * plugin, GstStructure *cache_data);

GST_API

gboolean		gst_plugin_is_loaded		(GstPlugin *plugin);

GST_API

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

GST_API

GstPlugin *             gst_plugin_load                 (GstPlugin *plugin);

GST_API

GstPlugin *             gst_plugin_load_by_name         (const gchar *name);

GST_API

void                    gst_plugin_add_dependency        (GstPlugin    * plugin,

                                                          const gchar ** env_vars,

                                                          const gchar ** paths,

                                                          const gchar ** names,

                                                          GstPluginDependencyFlags flags);

GST_API

void                    gst_plugin_add_dependency_simple (GstPlugin   * plugin,

                                                          const gchar * env_vars,

                                                          const gchar * paths,

                                                          const gchar * names,

                                                          GstPluginDependencyFlags flags);

GST_API

void                    gst_plugin_list_free (GList *list);

#ifdef G_DEFINE_AUTOPTR_CLEANUP_FUNC

G_DEFINE_AUTOPTR_CLEANUP_FUNC(GstPlugin, gst_object_unref)

#endif

G_END_DECLS

#endif /* __GST_PLUGIN_H__ */