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 | |
33 | G_BEGIN_DECLS |
34 | |
35 | /** |
36 | * GstPlugin: |
37 | * |
38 | * The opaque plugin object |
39 | */ |
40 | typedef struct _GstPlugin GstPlugin; |
41 | typedef struct _GstPluginClass GstPluginClass; |
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 | |
52 | GST_API |
53 | GQuark 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 | */ |
69 | typedef 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 | */ |
83 | typedef 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 | */ |
107 | typedef 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 */ |
128 | typedef 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 */ |
144 | typedef 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 | */ |
171 | struct _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) \ |
256 | G_BEGIN_DECLS \ |
257 | GST_PLUGIN_EXPORT const GstPluginDesc * G_PASTE(gst_plugin_, G_PASTE(name, _get_desc)) (void); \ |
258 | GST_PLUGIN_EXPORT void G_PASTE(gst_plugin_, G_PASTE(name, _register)) (void); \ |
259 | \ |
260 | static 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 | \ |
275 | const GstPluginDesc * \ |
276 | G_PASTE(gst_plugin_, G_PASTE(name, _get_desc)) (void) \ |
277 | { \ |
278 | return &gst_plugin_desc; \ |
279 | } \ |
280 | \ |
281 | void \ |
282 | G_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 | } \ |
288 | G_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 | */ |
309 | typedef gboolean (*GstPluginFilter) (GstPlugin *plugin, |
310 | gpointer user_data); |
311 | |
312 | GST_API |
313 | GType gst_plugin_get_type (void); |
314 | |
315 | GST_API |
316 | gboolean 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); |
326 | GST_API |
327 | gboolean 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); |
338 | GST_API |
339 | const gchar* gst_plugin_get_name (GstPlugin *plugin); |
340 | |
341 | GST_API |
342 | const gchar* gst_plugin_get_description (GstPlugin *plugin); |
343 | |
344 | GST_API |
345 | const gchar* gst_plugin_get_filename (GstPlugin *plugin); |
346 | |
347 | GST_API |
348 | const gchar* gst_plugin_get_version (GstPlugin *plugin); |
349 | |
350 | GST_API |
351 | const gchar* gst_plugin_get_license (GstPlugin *plugin); |
352 | |
353 | GST_API |
354 | const gchar* gst_plugin_get_source (GstPlugin *plugin); |
355 | |
356 | GST_API |
357 | const gchar* gst_plugin_get_package (GstPlugin *plugin); |
358 | |
359 | GST_API |
360 | const gchar* gst_plugin_get_origin (GstPlugin *plugin); |
361 | |
362 | GST_API |
363 | const gchar* gst_plugin_get_release_date_string (GstPlugin *plugin); |
364 | |
365 | GST_API |
366 | const GstStructure* gst_plugin_get_cache_data (GstPlugin * plugin); |
367 | |
368 | GST_API |
369 | void gst_plugin_set_cache_data (GstPlugin * plugin, GstStructure *cache_data); |
370 | |
371 | GST_API |
372 | gboolean gst_plugin_is_loaded (GstPlugin *plugin); |
373 | |
374 | GST_API |
375 | GstPlugin * gst_plugin_load_file (const gchar *filename, GError** error); |
376 | |
377 | GST_API |
378 | GstPlugin * gst_plugin_load (GstPlugin *plugin); |
379 | |
380 | GST_API |
381 | GstPlugin * gst_plugin_load_by_name (const gchar *name); |
382 | |
383 | GST_API |
384 | void gst_plugin_add_dependency (GstPlugin * plugin, |
385 | const gchar ** env_vars, |
386 | const gchar ** paths, |
387 | const gchar ** names, |
388 | GstPluginDependencyFlags flags); |
389 | GST_API |
390 | void gst_plugin_add_dependency_simple (GstPlugin * plugin, |
391 | const gchar * env_vars, |
392 | const gchar * paths, |
393 | const gchar * names, |
394 | GstPluginDependencyFlags flags); |
395 | GST_API |
396 | void gst_plugin_list_free (GList *list); |
397 | |
398 | G_DEFINE_AUTOPTR_CLEANUP_FUNC(GstPlugin, gst_object_unref) |
399 | |
400 | G_END_DECLS |
401 | |
402 | #endif /* __GST_PLUGIN_H__ */ |
403 | |