subprojects/gstreamer/gst/gsttypefind.h

   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   /* <private> */
 176   gpointer _gst_reserved[GST_PADDING];
 177 };
 178
 179 /**
 180  * gst_type_find_get_type: (attributes doc.skip=true)
 181  */
 182 GST_API
 183 GType     gst_type_find_get_type   (void);
 184
 185 /* typefind function interface */
 186
 187 GST_API
 188 const guint8 *  gst_type_find_peek       (GstTypeFind   * find,
 189                                           gint64          offset,
 190                                           guint           size);
 191 GST_API
 192 void            gst_type_find_suggest    (GstTypeFind   * find,
 193                                           guint           probability,
 194                                           GstCaps       * caps);
 195 GST_API
 196 void            gst_type_find_suggest_empty_simple (GstTypeFind * find,
 197                                                     guint         probability,
 198                                                     const char  * media_type);
 199 GST_API
 200 void            gst_type_find_suggest_simple (GstTypeFind * find,
 201                                               guint         probability,
 202                                               const char  * media_type,
 203                                               const char  * fieldname, ...) G_GNUC_NULL_TERMINATED;
 204 GST_API
 205 guint64   gst_type_find_get_length (GstTypeFind   * find);
 206
 207 /* registration interface */
 208
 209 GST_API
 210 gboolean  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
 219 G_END_DECLS
 220
 221 #endif /* __GST_TYPE_FIND_H__ */