1/* GStreamer
2 * Copyright (C) 2003 Benjamin Otte <[email protected]>
3 *
4 * gsttypefind.h: typefinding subsystem
5 *
6 * This library is free software; you can redistribute it and/or
7 * modify it under the terms of the GNU Library General Public
8 * License as published by the Free Software Foundation; either
9 * version 2 of the License, or (at your option) any later version.
10 *
11 * This library is distributed in the hope that it will be useful,
12 * but WITHOUT ANY WARRANTY; without even the implied warranty of
13 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
14 * Library General Public License for more details.
15 *
16 * You should have received a copy of the GNU Library General Public
17 * License along with this library; if not, write to the
18 * Free Software Foundation, Inc., 51 Franklin St, Fifth Floor,
19 * Boston, MA 02110-1301, USA.
20 */
21
22
23#ifndef __GST_TYPE_FIND_H__
24#define __GST_TYPE_FIND_H__
25
26#include <gst/gstcaps.h>
27#include <gst/gstplugin.h>
28#include <gst/gstpluginfeature.h>
29
30G_BEGIN_DECLS
31/**
32 * GST_TYPE_FIND_REGISTER_DEFINE_CUSTOM:
33 * @type_find: The type find name in lower case, with words separated by '_'.
34 * Used to generate `gst_type_find_register_*(GstPlugin* plugin)`.
35 * @register_func: pointer to a method with the format: `gboolean register_func (GstPlugin* plugin);`
36 *
37 * A convenience macro to define the entry point of a
38 * type find `gst_type_find_register_*(GstPlugin* plugin)` which uses
39 * register_func as the main registration method for the type find.
40 * As an example, you may define the type find named "custom-typefind"
41 * as following using `type_find_register_custom`:
42 *
43 * ```
44 * GST_TYPE_FIND_REGISTER_DEFINE_CUSTOM (plugin, type_find_register_custom)
45 * ```
46 *
47 * Since: 1.20
48 */
49#define GST_TYPE_FIND_REGISTER_DEFINE_CUSTOM(type_find, register_func) \
50G_BEGIN_DECLS \
51gboolean G_PASTE (gst_type_find_register_, type_find) (GstPlugin * plugin) \
52{ \
53 return register_func (plugin); \
54} \
55G_END_DECLS
56
57/**
58 * GST_TYPE_FIND_REGISTER_DEFINE:
59 * @t_f: The type find name in lower case, with words separated by '_'.
60 * Used to generate `gst_type_find_register_*(GstPlugin* plugin)`.
61 * @t_f_n: The public name of the type find
62 * @r: The #GstRank of the type find (higher rank means more importance when autoplugging, see #GstRank)
63 * @func: The #GstTypeFindFunction to use
64 * @extensions: (nullable): Optional comma-separated list of extensions
65 * that could belong to this type
66 * @possible_caps: (nullable): Optionally the caps that could be returned when typefinding
67 * succeeds
68 * @data: Optional user data. This user data must be available until the plugin
69 * is unloaded.
70 * @data_notify: a #GDestroyNotify that will be called on @data when the plugin
71 * is unloaded.
72 *
73 * A convenience macro to define the entry point of a
74 * type find `gst_type_find_register_*(GstPlugin* plugin)`.
75 *
76 * Since: 1.20
77 */
78#define GST_TYPE_FIND_REGISTER_DEFINE(t_f, t_f_n, r, func, extensions, possible_caps, data, data_notify) \
79G_BEGIN_DECLS \
80gboolean G_PASTE (gst_type_find_register_, t_f) (GstPlugin * plugin) \
81{ \
82 return gst_type_find_register (plugin, t_f_n, r, func, extensions, possible_caps, data, data_notify); \
83} \
84G_END_DECLS
85
86/**
87 * GST_TYPE_FIND_REGISTER_DECLARE:
88 * @t_f: The type find name in lower case, with words separated by '_'.
89 *
90 * This macro can be used to declare a new type find.
91 * It has to be used in combination with #GST_TYPE_FIND_REGISTER_DEFINE macro
92 * and must be placed outside any block to declare the type find registration
93 * function.
94 *
95 * Since: 1.20
96 */
97#define GST_TYPE_FIND_REGISTER_DECLARE(t_f) \
98G_BEGIN_DECLS \
99gboolean G_PASTE(gst_type_find_register_, t_f) (GstPlugin * plugin); \
100G_END_DECLS
101
102/**
103 * GST_TYPE_FIND_REGISTER:
104 * @t_f: The type find name in lower case, with words separated by '_'.
105 * @plugin: The #GstPlugin where to register the type find.
106
107 *
108 * This macro can be used to register a type find into a #GstPlugin.
109 * This method will be usually called in the plugin init function
110 * but can also be called with a NULL plugin.
111 *
112 * Since: 1.20
113 */
114#define GST_TYPE_FIND_REGISTER(t_f, plugin) G_PASTE(gst_type_find_register_, t_f) (plugin)
115
116
117#define GST_TYPE_TYPE_FIND (gst_type_find_get_type())
118
119typedef struct _GstTypeFind GstTypeFind;
120
121/**
122 * GstTypeFindFunction:
123 * @find: A #GstTypeFind structure
124 * @user_data: optional data to pass to the function
125 *
126 * A function that will be called by typefinding.
127 */
128typedef void (* GstTypeFindFunction) (GstTypeFind *find, gpointer user_data);
129
130/**
131 * GstTypeFindProbability:
132 * @GST_TYPE_FIND_NONE: type undetected.
133 * @GST_TYPE_FIND_MINIMUM: unlikely typefind.
134 * @GST_TYPE_FIND_POSSIBLE: possible type detected.
135 * @GST_TYPE_FIND_LIKELY: likely a type was detected.
136 * @GST_TYPE_FIND_NEARLY_CERTAIN: nearly certain that a type was detected.
137 * @GST_TYPE_FIND_MAXIMUM: very certain a type was detected.
138 *
139 * The probability of the typefind function. Higher values have more certainty
140 * in doing a reliable typefind.
141 */
142typedef enum {
143 GST_TYPE_FIND_NONE = 0,
144 GST_TYPE_FIND_MINIMUM = 1,
145 GST_TYPE_FIND_POSSIBLE = 50,
146 GST_TYPE_FIND_LIKELY = 80,
147 GST_TYPE_FIND_NEARLY_CERTAIN = 99,
148 GST_TYPE_FIND_MAXIMUM = 100
149} GstTypeFindProbability;
150
151/**
152 * GstTypeFind:
153 * @peek: Method to peek data.
154 * @suggest: Method to suggest #GstCaps with a given probability.
155 * @data: The data used by the caller of the typefinding function.
156 * @get_length: Returns the length of current data.
157 *
158 * Object that stores typefind callbacks. To use with #GstTypeFindFactory.
159 */
160struct _GstTypeFind {
161 /* private to the caller of the typefind function */
162 const guint8 * (* peek) (gpointer data,
163 gint64 offset,
164 guint size);
165
166 void (* suggest) (gpointer data,
167 guint probability,
168 GstCaps *caps);
169
170 gpointer data;
171
172 /* optional */
173 guint64 (* get_length) (gpointer data);
174
175 /* <private> */
176 gpointer _gst_reserved[GST_PADDING];
177};
178
179/**
180 * gst_type_find_get_type: (attributes doc.skip=true)
181 */
182GST_API
183GType gst_type_find_get_type (void);
184
185/* typefind function interface */
186
187GST_API
188const guint8 * gst_type_find_peek (GstTypeFind * find,
189 gint64 offset,
190 guint size);
191GST_API
192void gst_type_find_suggest (GstTypeFind * find,
193 guint probability,
194 GstCaps * caps);
195GST_API
196void gst_type_find_suggest_empty_simple (GstTypeFind * find,
197 guint probability,
198 const char * media_type);
199GST_API
200void gst_type_find_suggest_simple (GstTypeFind * find,
201 guint probability,
202 const char * media_type,
203 const char * fieldname, ...) G_GNUC_NULL_TERMINATED;
204GST_API
205guint64 gst_type_find_get_length (GstTypeFind * find);
206
207/* registration interface */
208
209GST_API
210gboolean gst_type_find_register (GstPlugin * plugin,
211 const gchar * name,
212 guint rank,
213 GstTypeFindFunction func,
214 const gchar * extensions,
215 GstCaps * possible_caps,
216 gpointer data,
217 GDestroyNotify data_notify);
218
219G_END_DECLS
220
221#endif /* __GST_TYPE_FIND_H__ */
222

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