• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1 /* GStreamer
2  * Copyright (C) 2003 Benjamin Otte <in7y118@public.uni-hamburg.de>
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 
30 G_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) \
50 G_BEGIN_DECLS \
51 gboolean G_PASTE (gst_type_find_register_, type_find) (GstPlugin * plugin) \
52 { \
53   return register_func (plugin); \
54 } \
55 G_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) \
79 G_BEGIN_DECLS \
80 gboolean 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 } \
84 G_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) \
98 G_BEGIN_DECLS \
99 gboolean G_PASTE(gst_type_find_register_, t_f) (GstPlugin * plugin); \
100 G_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 
119 typedef 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  */
128 typedef 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  */
142 typedef 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  */
160 struct _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 #ifdef OHOS_EXT_FUNC
176   /**
177    * ohos.ext.func.0039
178    * Disable do subtitle typefind.
179    * Return TRUE not do sub typefind, FALSE do sub typefind.
180    */
181   gboolean        (* is_mask_sub) (gpointer data);
182 #endif
183 
184 #ifdef OHOS_OPT_COMPAT
185   // ohos.opt.compat.0004
186   gboolean need_typefind_again;
187 #endif
188 
189   /* <private> */
190   gpointer _gst_reserved[GST_PADDING];
191 };
192 
193 /**
194  * gst_type_find_get_type: (attributes doc.skip=true)
195  */
196 GST_API
197 GType     gst_type_find_get_type   (void);
198 
199 /* typefind function interface */
200 
201 GST_API
202 const guint8 *  gst_type_find_peek       (GstTypeFind   * find,
203                                           gint64          offset,
204                                           guint           size);
205 GST_API
206 void            gst_type_find_suggest    (GstTypeFind   * find,
207                                           guint           probability,
208                                           GstCaps       * caps);
209 GST_API
210 void            gst_type_find_suggest_empty_simple (GstTypeFind * find,
211                                                     guint         probability,
212                                                     const char  * media_type);
213 GST_API
214 void            gst_type_find_suggest_simple (GstTypeFind * find,
215                                               guint         probability,
216                                               const char  * media_type,
217                                               const char  * fieldname, ...) G_GNUC_NULL_TERMINATED;
218 GST_API
219 guint64   gst_type_find_get_length (GstTypeFind   * find);
220 
221 #ifdef OHOS_EXT_FUNC
222 // ohos.ext.func.0039
223 GST_API
224 gboolean  gst_type_find_is_mask_sub (const GstTypeFind *find);
225 #endif
226 
227 /* registration interface */
228 
229 GST_API
230 gboolean  gst_type_find_register   (GstPlugin            * plugin,
231                                     const gchar          * name,
232                                     guint                  rank,
233                                     GstTypeFindFunction    func,
234                                     const gchar          * extensions,
235                                     GstCaps              * possible_caps,
236                                     gpointer               data,
237                                     GDestroyNotify         data_notify);
238 
239 G_END_DECLS
240 
241 #endif /* __GST_TYPE_FIND_H__ */
242