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., 51 Franklin St, Fifth Floor,
20 * Boston, MA 02110-1301, USA.
21 */
22
23
24#ifndef __GST_PLUGIN_H__
25#define __GST_PLUGIN_H__
26
27#include <gst/gstconfig.h>
28
29#include <gst/gstobject.h>
30#include <gst/gstmacros.h>
31#include <gst/gststructure.h>
32
33G_BEGIN_DECLS
34
35/**
36 * GstPlugin:
37 *
38 * The opaque plugin object
39 */
40typedef struct _GstPlugin GstPlugin;
41typedef struct _GstPluginClass GstPluginClass;
42typedef 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
52GST_API
53GQuark gst_plugin_error_quark (void);
54/**
55 * GST_PLUGIN_ERROR:
56 *
57 * The error message category quark
58 */
59#define GST_PLUGIN_ERROR gst_plugin_error_quark ()
60
61/**
62 * GstPluginError:
63 * @GST_PLUGIN_ERROR_MODULE: The plugin could not be loaded
64 * @GST_PLUGIN_ERROR_DEPENDENCIES: The plugin has unresolved dependencies
65 * @GST_PLUGIN_ERROR_NAME_MISMATCH: The plugin has already be loaded from a different file
66 *
67 * The plugin loading errors
68 */
69typedef enum
70{
71 GST_PLUGIN_ERROR_MODULE,
72 GST_PLUGIN_ERROR_DEPENDENCIES,
73 GST_PLUGIN_ERROR_NAME_MISMATCH
74} GstPluginError;
75
76/**
77 * GstPluginFlags:
78 * @GST_PLUGIN_FLAG_CACHED: Temporarily loaded plugins
79 * @GST_PLUGIN_FLAG_BLACKLISTED: The plugin won't be scanned (again)
80 *
81 * The plugin loading state
82 */
83typedef enum
84{
85 GST_PLUGIN_FLAG_CACHED = (GST_OBJECT_FLAG_LAST << 0),
86 GST_PLUGIN_FLAG_BLACKLISTED = (GST_OBJECT_FLAG_LAST << 1)
87} GstPluginFlags;
88
89/**
90 * GstPluginDependencyFlags:
91 * @GST_PLUGIN_DEPENDENCY_FLAG_NONE : no special flags
92 * @GST_PLUGIN_DEPENDENCY_FLAG_RECURSE : recurse into subdirectories
93 * @GST_PLUGIN_DEPENDENCY_FLAG_PATHS_ARE_DEFAULT_ONLY : use paths
94 * argument only if none of the environment variables is set
95 * @GST_PLUGIN_DEPENDENCY_FLAG_FILE_NAME_IS_SUFFIX : interpret
96 * filename argument as filter suffix and check all matching files in
97 * the directory
98 * @GST_PLUGIN_DEPENDENCY_FLAG_FILE_NAME_IS_PREFIX : interpret
99 * filename argument as filter prefix and check all matching files in
100 * the directory. Since: 1.8.
101 * @GST_PLUGIN_DEPENDENCY_FLAG_PATHS_ARE_RELATIVE_TO_EXE : interpret
102 * non-absolute paths as relative to the main executable directory. Since
103 * 1.14.
104 *
105 * Flags used in connection with gst_plugin_add_dependency().
106 */
107typedef enum {
108 GST_PLUGIN_DEPENDENCY_FLAG_NONE = 0,
109 GST_PLUGIN_DEPENDENCY_FLAG_RECURSE = (1 << 0),
110 GST_PLUGIN_DEPENDENCY_FLAG_PATHS_ARE_DEFAULT_ONLY = (1 << 1),
111 GST_PLUGIN_DEPENDENCY_FLAG_FILE_NAME_IS_SUFFIX = (1 << 2),
112 GST_PLUGIN_DEPENDENCY_FLAG_FILE_NAME_IS_PREFIX = (1 << 3),
113 GST_PLUGIN_DEPENDENCY_FLAG_PATHS_ARE_RELATIVE_TO_EXE = (1 << 4)
114} GstPluginDependencyFlags;
115
116/**
117 * GstPluginInitFunc:
118 * @plugin: The plugin object
119 *
120 * A plugin should provide a pointer to a function of this type in the
121 * plugin_desc struct.
122 * This function will be called by the loader at startup. One would then
123 * register each #GstPluginFeature.
124 *
125 * Returns: %TRUE if plugin initialised successfully
126 */
127/* FIXME 0.11: Make return void */
128typedef gboolean (*GstPluginInitFunc) (GstPlugin *plugin);
129
130/**
131 * GstPluginInitFullFunc:
132 * @plugin: The plugin object
133 * @user_data: extra data
134 *
135 * A plugin should provide a pointer to a function of either #GstPluginInitFunc
136 * or this type in the plugin_desc struct.
137 * The function will be called by the loader at startup. One would then
138 * register each #GstPluginFeature. This version allows
139 * user data to be passed to init function (useful for bindings).
140 *
141 * Returns: %TRUE if plugin initialised successfully
142 */
143/* FIXME 0.11: Merge with GstPluginInitFunc */
144typedef gboolean (*GstPluginInitFullFunc) (GstPlugin *plugin, gpointer user_data);
145
146/**
147 * GstPluginDesc:
148 * @major_version: the major version number of core that plugin was compiled for
149 * @minor_version: the minor version number of core that plugin was compiled for
150 * @name: a unique name of the plugin
151 * @description: description of plugin
152 * @plugin_init: pointer to the init function of this plugin.
153 * @version: version of the plugin
154 * @license: effective license of plugin
155 * @source: source module plugin belongs to
156 * @package: shipped package plugin belongs to
157 * @origin: URL to provider of plugin
158 * @release_datetime: (allow-none): date time string in ISO 8601
159 * format (or rather, a subset thereof), or %NULL. Allowed are the
160 * following formats: "YYYY-MM-DD" and "YYY-MM-DDTHH:MMZ" (with
161 * 'T' a separator and 'Z' indicating UTC/Zulu time). This field
162 * should be set via the GST_PACKAGE_RELEASE_DATETIME
163 * preprocessor macro.
164 *
165 * A plugin should export a variable of this type called plugin_desc. The plugin
166 * loader will use the data provided there to initialize the plugin.
167 *
168 * The @licence parameter must be one of: LGPL, GPL, QPL, GPL/QPL, MPL,
169 * BSD, MIT/X11, Proprietary, unknown.
170 */
171struct _GstPluginDesc {
172 gint major_version;
173 gint minor_version;
174 const gchar *name;
175 const gchar *description;
176 GstPluginInitFunc plugin_init;
177 const gchar *version;
178 const gchar *license;
179 const gchar *source;
180 const gchar *package;
181 const gchar *origin;
182 const gchar *release_datetime;
183 /*< private >*/
184 gpointer _gst_reserved[GST_PADDING];
185};
186
187
188#define GST_TYPE_PLUGIN (gst_plugin_get_type())
189#define GST_IS_PLUGIN(obj) (G_TYPE_CHECK_INSTANCE_TYPE ((obj), GST_TYPE_PLUGIN))
190#define GST_IS_PLUGIN_CLASS(klass) (G_TYPE_CHECK_CLASS_TYPE ((klass), GST_TYPE_PLUGIN))
191#define GST_PLUGIN_GET_CLASS(obj) (G_TYPE_INSTANCE_GET_CLASS ((obj), GST_TYPE_PLUGIN, GstPluginClass))
192#define GST_PLUGIN(obj) (G_TYPE_CHECK_INSTANCE_CAST ((obj), GST_TYPE_PLUGIN, GstPlugin))
193#define GST_PLUGIN_CLASS(klass) (G_TYPE_CHECK_CLASS_CAST ((klass), GST_TYPE_PLUGIN, GstPluginClass))
194#define GST_PLUGIN_CAST(obj) ((GstPlugin*)(obj))
195
196#ifdef GST_PACKAGE_RELEASE_DATETIME
197#define __GST_PACKAGE_RELEASE_DATETIME GST_PACKAGE_RELEASE_DATETIME
198#else
199#define __GST_PACKAGE_RELEASE_DATETIME NULL
200#endif
201
202/**
203 * GST_PLUGIN_STATIC_DECLARE:
204 * @name: short, but unique name of the plugin
205 *
206 * This macro can be used to initialize statically linked plugins. It is
207 * necessary to call this macro before the plugin can be used.
208 * It has to be used in combination with GST_PLUGIN_STATIC_REGISTER
209 * and must be placed outside any block to declare the plugin initialization
210 * function.
211 *
212 * Since: 1.2
213 */
214#define GST_PLUGIN_STATIC_DECLARE(name) \
215 extern void G_PASTE(gst_plugin_, G_PASTE(name, _register)) (void)
216
217/**
218 * GST_PLUGIN_STATIC_REGISTER:
219 * @name: short, but unique name of the plugin
220 *
221 * This macro can be used to initialize statically linked plugins. It is
222 * necessary to call this macro before the plugin can be used.
223 * It has to be used in combination with GST_PLUGIN_STATIC_DECLARE and
224 * calls the plugin initialization function.
225 *
226 * Since: 1.2
227 */
228#define GST_PLUGIN_STATIC_REGISTER(name) G_PASTE(gst_plugin_, G_PASTE(name, _register)) ()
229
230/**
231 * GST_PLUGIN_DEFINE:
232 * @major: major version number of the gstreamer-core that plugin was compiled for
233 * @minor: minor version number of the gstreamer-core that plugin was compiled for
234 * @name: short, but unique name of the plugin
235 * @description: information about the purpose of the plugin
236 * @init: function pointer to the plugin_init method with the signature of <code>static gboolean plugin_init (GstPlugin * plugin)</code>.
237 * @version: full version string (e.g. VERSION from config.h)
238 * @license: under which licence the package has been released, e.g. GPL, LGPL.
239 * @package: the package-name (e.g. PACKAGE_NAME from config.h)
240 * @origin: a description from where the package comes from (e.g. the homepage URL)
241 *
242 * This macro needs to be used to define the entry point and meta data of a
243 * plugin. One would use this macro to export a plugin, so that it can be used
244 * by other applications.
245 *
246 * The macro uses a define named PACKAGE for the #GstPluginDesc,source field.
247 * When using autoconf, this is usually set automatically via the AC_INIT
248 * macro, and set in config.h. If you are not using autoconf, you will need to
249 * define PACKAGE yourself and set it to a short mnemonic string identifying
250 * your application/package, e.g. 'someapp' or 'my-plugins-foo.
251 *
252 * If defined, the GST_PACKAGE_RELEASE_DATETIME will also be used for the
253 * #GstPluginDesc,release_datetime field.
254 */
255#define GST_PLUGIN_DEFINE(major,minor,name,description,init,version,license,package,origin) \
256G_BEGIN_DECLS \
257GST_PLUGIN_EXPORT const GstPluginDesc * G_PASTE(gst_plugin_, G_PASTE(name, _get_desc)) (void); \
258GST_PLUGIN_EXPORT void G_PASTE(gst_plugin_, G_PASTE(name, _register)) (void); \
259\
260static const GstPluginDesc gst_plugin_desc = { \
261 major, \
262 minor, \
263 G_STRINGIFY(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\
275const GstPluginDesc * \
276G_PASTE(gst_plugin_, G_PASTE(name, _get_desc)) (void) \
277{ \
278 return &gst_plugin_desc; \
279} \
280\
281void \
282G_PASTE(gst_plugin_, G_PASTE(name, _register)) (void) \
283{ \
284 gst_plugin_register_static (major, minor, G_STRINGIFY(name), \
285 description, init, version, license, \
286 PACKAGE, package, origin); \
287} \
288G_END_DECLS
289
290/**
291 * GST_LICENSE_UNKNOWN:
292 *
293 * To be used in GST_PLUGIN_DEFINE if unsure about the licence.
294 */
295#define GST_LICENSE_UNKNOWN "unknown"
296
297
298/* function for filters */
299/**
300 * GstPluginFilter:
301 * @plugin: the plugin to check
302 * @user_data: the user_data that has been passed on e.g. gst_registry_plugin_filter()
303 *
304 * A function that can be used with e.g. gst_registry_plugin_filter()
305 * to get a list of plugins that match certain criteria.
306 *
307 * Returns: %TRUE for a positive match, %FALSE otherwise
308 */
309typedef gboolean (*GstPluginFilter) (GstPlugin *plugin,
310 gpointer user_data);
311
312GST_API
313GType gst_plugin_get_type (void);
314
315GST_API
316gboolean gst_plugin_register_static (gint major_version,
317 gint minor_version,
318 const gchar *name,
319 const gchar *description,
320 GstPluginInitFunc init_func,
321 const gchar *version,
322 const gchar *license,
323 const gchar *source,
324 const gchar *package,
325 const gchar *origin);
326GST_API
327gboolean gst_plugin_register_static_full (gint major_version,
328 gint minor_version,
329 const gchar *name,
330 const gchar *description,
331 GstPluginInitFullFunc init_full_func,
332 const gchar *version,
333 const gchar *license,
334 const gchar *source,
335 const gchar *package,
336 const gchar *origin,
337 gpointer user_data);
338GST_API
339const gchar* gst_plugin_get_name (GstPlugin *plugin);
340
341GST_API
342const gchar* gst_plugin_get_description (GstPlugin *plugin);
343
344GST_API
345const gchar* gst_plugin_get_filename (GstPlugin *plugin);
346
347GST_API
348const gchar* gst_plugin_get_version (GstPlugin *plugin);
349
350GST_API
351const gchar* gst_plugin_get_license (GstPlugin *plugin);
352
353GST_API
354const gchar* gst_plugin_get_source (GstPlugin *plugin);
355
356GST_API
357const gchar* gst_plugin_get_package (GstPlugin *plugin);
358
359GST_API
360const gchar* gst_plugin_get_origin (GstPlugin *plugin);
361
362GST_API
363const gchar* gst_plugin_get_release_date_string (GstPlugin *plugin);
364
365GST_API
366const GstStructure* gst_plugin_get_cache_data (GstPlugin * plugin);
367
368GST_API
369void gst_plugin_set_cache_data (GstPlugin * plugin, GstStructure *cache_data);
370
371GST_API
372gboolean gst_plugin_is_loaded (GstPlugin *plugin);
373
374GST_API
375GstPlugin * gst_plugin_load_file (const gchar *filename, GError** error);
376
377GST_API
378GstPlugin * gst_plugin_load (GstPlugin *plugin);
379
380GST_API
381GstPlugin * gst_plugin_load_by_name (const gchar *name);
382
383GST_API
384void gst_plugin_add_dependency (GstPlugin * plugin,
385 const gchar ** env_vars,
386 const gchar ** paths,
387 const gchar ** names,
388 GstPluginDependencyFlags flags);
389GST_API
390void gst_plugin_add_dependency_simple (GstPlugin * plugin,
391 const gchar * env_vars,
392 const gchar * paths,
393 const gchar * names,
394 GstPluginDependencyFlags flags);
395GST_API
396void gst_plugin_list_free (GList *list);
397
398G_DEFINE_AUTOPTR_CLEANUP_FUNC(GstPlugin, gst_object_unref)
399
400G_END_DECLS
401
402#endif /* __GST_PLUGIN_H__ */
403

source code of include/gstreamer-1.0/gst/gstplugin.h