Merge remote-tracking branch 'origin/master' into 0.11
[platform/upstream/gstreamer.git] / 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 /* FIXME 0.11: Make return void */
120 typedef gboolean (*GstPluginInitFunc) (GstPlugin *plugin);
121
122 /**
123  * GstPluginInitFullFunc:
124  * @plugin: The plugin object
125  * @user_data: extra data
126  *
127  * A plugin should provide a pointer to a function of either #GstPluginInitFunc
128  * or this type in the plugin_desc struct.
129  * The function will be called by the loader at startup. One would then
130  * register each #GstPluginFeature. This version allows
131  * user data to be passed to init function (useful for bindings).
132  *
133  * Returns: %TRUE if plugin initialised successfully
134  *
135  * Since: 0.10.24
136  *
137  */
138 /* FIXME 0.11: Merge with GstPluginInitFunc */
139 typedef gboolean (*GstPluginInitFullFunc) (GstPlugin *plugin, gpointer user_data);
140
141 /**
142  * GstPluginDesc:
143  * @major_version: the major version number of core that plugin was compiled for
144  * @minor_version: the minor version number of core that plugin was compiled for
145  * @name: a unique name of the plugin
146  * @description: description of plugin
147  * @plugin_init: pointer to the init function of this plugin.
148  * @version: version of the plugin
149  * @license: effective license of plugin
150  * @source: source module plugin belongs to
151  * @package: shipped package plugin belongs to
152  * @origin: URL to provider of plugin
153  * @release_datetime: date time string in ISO 8601 format (or rather, a
154  *     subset thereof), or NULL. Allowed are the following formats:
155  *     "YYYY-MM-DD" and "YYY-MM-DDTHH:MMZ" (with 'T' a separator and 'Z'
156  *     indicating UTC/Zulu time). This field should be set via the
157  *     GST_PACKAGE_RELEASE_DATETIME preprocessor macro (Since: 0.10.31)
158  *
159  * A plugin should export a variable of this type called plugin_desc. The plugin
160  * 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   gint major_version;
167   gint minor_version;
168   const gchar *name;
169   const gchar *description;
170   GstPluginInitFunc plugin_init;
171   const gchar *version;
172   const gchar *license;
173   const gchar *source;
174   const gchar *package;
175   const gchar *origin;
176   const gchar *release_datetime;
177   /*< private >*/
178   gpointer _gst_reserved[GST_PADDING];
179 };
180
181
182 #define GST_TYPE_PLUGIN   (gst_plugin_get_type())
183 #define GST_IS_PLUGIN(obj)             (G_TYPE_CHECK_INSTANCE_TYPE ((obj), GST_TYPE_PLUGIN))
184 #define GST_IS_PLUGIN_CLASS(klass)     (G_TYPE_CHECK_CLASS_TYPE ((klass), GST_TYPE_PLUGIN))
185 #define GST_PLUGIN_GET_CLASS(obj)      (G_TYPE_INSTANCE_GET_CLASS ((obj), GST_TYPE_PLUGIN, GstPluginClass))
186 #define GST_PLUGIN(obj)                (G_TYPE_CHECK_INSTANCE_CAST ((obj), GST_TYPE_PLUGIN, GstPlugin))
187 #define GST_PLUGIN_CLASS(klass)        (G_TYPE_CHECK_CLASS_CAST ((klass), GST_TYPE_PLUGIN, GstPluginClass))
188 #define GST_PLUGIN_CAST(obj)           ((GstPlugin*)(obj))
189
190 /**
191  * GstPlugin:
192  *
193  * The plugin object
194  */
195 struct _GstPlugin {
196   GstObject       object;
197
198   /*< private >*/
199   GstPluginDesc desc;
200
201   GstPluginDesc *orig_desc;
202
203   unsigned int  flags;
204
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
210   off_t         file_size;
211   time_t        file_mtime;
212   gboolean      registered;     /* TRUE when the registry has seen a filename
213                                  * that matches the plugin's basename */
214
215   GstPluginPrivate *priv;
216
217   gpointer _gst_reserved[GST_PADDING];
218 };
219
220 struct _GstPluginClass {
221   GstObjectClass  object_class;
222
223   /*< private >*/
224   gpointer _gst_reserved[GST_PADDING];
225 };
226
227 #ifdef GST_PACKAGE_RELEASE_DATETIME
228 #define __GST_PACKAGE_RELEASE_DATETIME GST_PACKAGE_RELEASE_DATETIME
229 #else
230 #define __GST_PACKAGE_RELEASE_DATETIME NULL
231 #endif
232
233 /**
234  * GST_PLUGIN_DEFINE:
235  * @major: major version number of the gstreamer-core that plugin was compiled for
236  * @minor: minor version number of the gstreamer-core that plugin was compiled for
237  * @name: short, but unique name of the plugin
238  * @description: information about the purpose of the plugin
239  * @init: function pointer to the plugin_init method with the signature of <code>static gboolean plugin_init (GstPlugin * plugin)</code>.
240  * @version: full version string (e.g. VERSION from config.h)
241  * @license: under which licence the package has been released, e.g. GPL, LGPL.
242  * @package: the package-name (e.g. PACKAGE_NAME from config.h)
243  * @origin: a description from where the package comes from (e.g. the homepage URL)
244  *
245  * This macro needs to be used to define the entry point and meta data of a
246  * plugin. One would use this macro to export a plugin, so that it can be used
247  * by other applications.
248  *
249  * The macro uses a define named PACKAGE for the #GstPluginDesc,source field.
250  * When using autoconf, this is usually set automatically via the AC_INIT
251  * macro, and set in config.h. If you are not using autoconf, you will need to
252  * define PACKAGE yourself and set it to a short mnemonic string identifying
253  * your application/package, e.g. 'someapp' or 'my-plugins-foo.
254  *
255  * If defined, the GST_PACKAGE_RELEASE_DATETIME will also be used for the
256  * #GstPluginDesc,release_datetime field.
257  */
258 #define GST_PLUGIN_DEFINE(major,minor,name,description,init,version,license,package,origin)     \
259 G_BEGIN_DECLS \
260 GST_PLUGIN_EXPORT GstPluginDesc gst_plugin_desc = {     \
261   major,                                                \
262   minor,                                                \
263   name,                                                 \
264   (gchar *) description,                                \
265   init,                                                 \
266   version,                                              \
267   license,                                              \
268   PACKAGE,                                              \
269   package,                                              \
270   origin,                                               \
271   __GST_PACKAGE_RELEASE_DATETIME,                       \
272   GST_PADDING_INIT                                      \
273 }; \
274 G_END_DECLS
275
276 /**
277  * GST_LICENSE_UNKNOWN:
278  *
279  * To be used in GST_PLUGIN_DEFINE or GST_PLUGIN_DEFINE_STATIC if usure about
280  * the licence.
281  */
282 #define GST_LICENSE_UNKNOWN "unknown"
283
284
285 /* function for filters */
286 /**
287  * GstPluginFilter:
288  * @plugin: the plugin to check
289  * @user_data: the user_data that has been passed on e.g. gst_registry_plugin_filter()
290  *
291  * A function that can be used with e.g. gst_registry_plugin_filter()
292  * to get a list of plugins that match certain criteria.
293  *
294  * Returns: TRUE for a positive match, FALSE otherwise
295  */
296 typedef gboolean        (*GstPluginFilter)              (GstPlugin *plugin,
297                                                          gpointer user_data);
298
299 GType                   gst_plugin_get_type             (void);
300
301 gboolean                gst_plugin_register_static      (gint major_version,
302                                                          gint minor_version,
303                                                          const gchar *name,
304                                                          const gchar *description,
305                                                          GstPluginInitFunc init_func,
306                                                          const gchar *version,
307                                                          const gchar *license,
308                                                          const gchar *source,
309                                                          const gchar *package,
310                                                          const gchar *origin);
311
312 gboolean                gst_plugin_register_static_full (gint major_version,
313                                                          gint minor_version,
314                                                          const gchar *name,
315                                                          const gchar *description,
316                                                          GstPluginInitFullFunc init_full_func,
317                                                          const gchar *version,
318                                                          const gchar *license,
319                                                          const gchar *source,
320                                                          const gchar *package,
321                                                          const gchar *origin,
322                                                          gpointer user_data);
323
324 const gchar*            gst_plugin_get_name             (GstPlugin *plugin);
325 const gchar*            gst_plugin_get_description      (GstPlugin *plugin);
326 const gchar*            gst_plugin_get_filename         (GstPlugin *plugin);
327 const gchar*            gst_plugin_get_version          (GstPlugin *plugin);
328 const gchar*            gst_plugin_get_license          (GstPlugin *plugin);
329 const gchar*            gst_plugin_get_source           (GstPlugin *plugin);
330 const gchar*            gst_plugin_get_package          (GstPlugin *plugin);
331 const gchar*            gst_plugin_get_origin           (GstPlugin *plugin);
332 const GstStructure*     gst_plugin_get_cache_data       (GstPlugin * plugin);
333 void                    gst_plugin_set_cache_data       (GstPlugin * plugin, GstStructure *cache_data);
334
335 GModule *               gst_plugin_get_module           (GstPlugin *plugin);
336 gboolean                gst_plugin_is_loaded            (GstPlugin *plugin);
337
338 gboolean                gst_plugin_name_filter          (GstPlugin *plugin, const gchar *name);
339
340 GstPlugin *             gst_plugin_load_file            (const gchar *filename, GError** error);
341
342 GstPlugin *             gst_plugin_load                 (GstPlugin *plugin);
343 GstPlugin *             gst_plugin_load_by_name         (const gchar *name);
344
345 void                    gst_plugin_add_dependency        (GstPlugin    * plugin,
346                                                           const gchar ** env_vars,
347                                                           const gchar ** paths,
348                                                           const gchar ** names,
349                                                           GstPluginDependencyFlags flags);
350 void                    gst_plugin_add_dependency_simple (GstPlugin   * plugin,
351                                                           const gchar * env_vars,
352                                                           const gchar * paths,
353                                                           const gchar * names,
354                                                           GstPluginDependencyFlags flags);
355
356 void gst_plugin_list_free (GList *list);
357
358 G_END_DECLS
359
360 #endif /* __GST_PLUGIN_H__ */