gst/gststructure.h

   1 /* GStreamer
   2  * Copyright (C) 2003 David A. Schleef <ds@schleef.org>
   3  *
   4  * This library is free software; you can redistribute it and/or
   5  * modify it under the terms of the GNU Library General Public
   6  * License as published by the Free Software Foundation; either
   7  * version 2 of the License, or (at your option) any later version.
   8  *
   9  * This library is distributed in the hope that it will be useful,
  10  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  11  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  12  * Library General Public License for more details.
  13  *
  14  * You should have received a copy of the GNU Library General Public
  15  * License along with this library; if not, write to the
  16  * Free Software Foundation, Inc., 51 Franklin St, Fifth Floor,
  17  * Boston, MA 02110-1301, USA.
  18  */
  19
  20 #ifndef __GST_STRUCTURE_H__
  21 #define __GST_STRUCTURE_H__
  22
  23 #include <gst/gstconfig.h>
  24 #include <glib-object.h>
  25 #include <gst/gstclock.h>
  26 #include <gst/gstdatetime.h>
  27 #include <gst/glib-compat.h>
  28
  29 G_BEGIN_DECLS
  30
  31 GST_EXPORT GType _gst_structure_type;
  32
  33 typedef struct _GstStructure GstStructure;
  34
  35 #define GST_TYPE_STRUCTURE             (_gst_structure_type)
  36 #define GST_IS_STRUCTURE(object)       ((object) && (GST_STRUCTURE(object)->type == GST_TYPE_STRUCTURE))
  37 #define GST_STRUCTURE_CAST(object)     ((GstStructure *)(object))
  38 #define GST_STRUCTURE(object)          (GST_STRUCTURE_CAST(object))
  39
  40
  41 /**
  42  * GstStructureForeachFunc:
  43  * @field_id: the #GQuark of the field name
  44  * @value: the #GValue of the field
  45  * @user_data: user data
  46  *
  47  * A function that will be called in gst_structure_foreach(). The function may
  48  * not modify @value.
  49  *
  50  * Returns: %TRUE if the foreach operation should continue, %FALSE if
  51  * the foreach operation should stop with %FALSE.
  52  */
  53 typedef gboolean (*GstStructureForeachFunc) (GQuark   field_id,
  54                                              const GValue * value,
  55                                              gpointer user_data);
  56
  57 /**
  58  * GstStructureMapFunc:
  59  * @field_id: the #GQuark of the field name
  60  * @value: the #GValue of the field
  61  * @user_data: user data
  62  *
  63  * A function that will be called in gst_structure_map_in_place(). The function
  64  * may modify @value.
  65  *
  66  * Returns: %TRUE if the map operation should continue, %FALSE if
  67  * the map operation should stop with %FALSE.
  68  */
  69 typedef gboolean (*GstStructureMapFunc)     (GQuark   field_id,
  70                                              GValue * value,
  71                                              gpointer user_data);
  72
  73 /**
  74  * GstStructureFilterMapFunc:
  75  * @field_id: the #GQuark of the field name
  76  * @value: the #GValue of the field
  77  * @user_data: user data
  78  *
  79  * A function that will be called in gst_structure_filter_and_map_in_place().
  80  * The function may modify @value, and the value will be removed from
  81  * the structure if %FALSE is returned.
  82  *
  83  * Returns: %TRUE if the field should be preserved, %FALSE if it
  84  * should be removed.
  85  */
  86 typedef gboolean (*GstStructureFilterMapFunc) (GQuark   field_id,
  87                                                GValue * value,
  88                                                gpointer user_data);
  89
  90 /**
  91  * GstStructure:
  92  * @type: the GType of a structure
  93  *
  94  * The GstStructure object. Most fields are private.
  95  */
  96 struct _GstStructure {
  97   GType type;
  98
  99   /*< private >*/
 100   GQuark name;
 101 };
 102
 103 GType                 gst_structure_get_type             (void);
 104
 105 GstStructure *        gst_structure_new_empty            (const gchar * name) G_GNUC_MALLOC;
 106
 107 GstStructure *        gst_structure_new_id_empty         (GQuark quark) G_GNUC_MALLOC;
 108
 109 GstStructure *        gst_structure_new                  (const gchar * name,
 110                                                           const gchar * firstfield,
 111                                                           ...) G_GNUC_NULL_TERMINATED  G_GNUC_MALLOC;
 112
 113 GstStructure *        gst_structure_new_valist           (const gchar * name,
 114                                                           const gchar * firstfield,
 115                                                           va_list       varargs) G_GNUC_MALLOC;
 116
 117 GstStructure *        gst_structure_new_id               (GQuark name_quark,
 118                                                           GQuark field_quark,
 119                                                           ...) G_GNUC_MALLOC;
 120
 121 GstStructure *        gst_structure_new_from_string      (const gchar * string);
 122
 123 GstStructure *        gst_structure_copy                 (const GstStructure  * structure) G_GNUC_MALLOC;
 124
 125 gboolean              gst_structure_set_parent_refcount  (GstStructure        * structure,
 126                                                             gint                * refcount);
 127
 128 void                  gst_structure_free                 (GstStructure        * structure);
 129
 130 const gchar *         gst_structure_get_name             (const GstStructure  * structure);
 131
 132 GQuark                gst_structure_get_name_id          (const GstStructure  * structure);
 133
 134 gboolean              gst_structure_has_name             (const GstStructure  * structure,
 135                                                           const gchar         * name);
 136
 137 void                  gst_structure_set_name             (GstStructure        * structure,
 138                                                           const gchar         * name);
 139
 140 void                  gst_structure_id_set_value         (GstStructure        * structure,
 141                                                           GQuark                field,
 142                                                           const GValue        * value);
 143
 144 void                  gst_structure_set_value            (GstStructure        * structure,
 145                                                           const gchar         * fieldname,
 146                                                           const GValue        * value);
 147
 148 void                  gst_structure_id_take_value        (GstStructure        * structure,
 149                                                           GQuark                field,
 150                                                           GValue              * value);
 151
 152 void                  gst_structure_take_value           (GstStructure        * structure,
 153                                                           const gchar         * fieldname,
 154                                                           GValue              * value);
 155
 156 void                  gst_structure_set                  (GstStructure        * structure,
 157                                                           const gchar         * fieldname,
 158                                                           ...) G_GNUC_NULL_TERMINATED;
 159
 160 void                  gst_structure_set_valist           (GstStructure        * structure,
 161                                                           const gchar         * fieldname,
 162                                                           va_list varargs);
 163
 164 void                  gst_structure_id_set               (GstStructure        * structure,
 165                                                           GQuark                fieldname,
 166                                                           ...) G_GNUC_NULL_TERMINATED;
 167
 168 void                  gst_structure_id_set_valist        (GstStructure        * structure,
 169                                                           GQuark                fieldname,
 170                                                           va_list varargs);
 171
 172 gboolean              gst_structure_get_valist           (const GstStructure  * structure,
 173                                                           const char          * first_fieldname,
 174                                                           va_list              args);
 175
 176 gboolean              gst_structure_get                  (const GstStructure  * structure,
 177                                                           const char          * first_fieldname,
 178                                                           ...) G_GNUC_NULL_TERMINATED;
 179
 180 gboolean              gst_structure_id_get_valist        (const GstStructure  * structure,
 181                                                           GQuark                first_field_id,
 182                                                           va_list               args);
 183
 184 gboolean              gst_structure_id_get               (const GstStructure  * structure,
 185                                                           GQuark                first_field_id,
 186                                                           ...) G_GNUC_NULL_TERMINATED;
 187
 188 const GValue *        gst_structure_id_get_value         (const GstStructure  * structure,
 189                                                           GQuark                field);
 190
 191 const GValue *        gst_structure_get_value            (const GstStructure  * structure,
 192                                                           const gchar         * fieldname);
 193
 194 void                  gst_structure_remove_field         (GstStructure        * structure,
 195                                                             const gchar         * fieldname);
 196
 197 void                  gst_structure_remove_fields        (GstStructure        * structure,
 198                                                           const gchar         * fieldname,
 199                                                           ...) G_GNUC_NULL_TERMINATED;
 200
 201 void                  gst_structure_remove_fields_valist (GstStructure        * structure,
 202                                                           const gchar         * fieldname,
 203                                                           va_list               varargs);
 204
 205 void                  gst_structure_remove_all_fields    (GstStructure        * structure);
 206
 207 GType                 gst_structure_get_field_type       (const GstStructure  * structure,
 208                                                           const gchar         * fieldname);
 209
 210 gboolean              gst_structure_foreach              (const GstStructure  * structure,
 211                                                           GstStructureForeachFunc   func,
 212                                                           gpointer              user_data);
 213
 214 gboolean              gst_structure_map_in_place         (GstStructure        * structure,
 215                                                           GstStructureMapFunc   func,
 216                                                           gpointer              user_data);
 217
 218 void                  gst_structure_filter_and_map_in_place (GstStructure        * structure,
 219                                                           GstStructureFilterMapFunc   func,
 220                                                           gpointer              user_data);
 221
 222 gint                  gst_structure_n_fields             (const GstStructure  * structure);
 223
 224 const gchar *         gst_structure_nth_field_name       (const GstStructure  * structure,
 225                                                           guint                 index);
 226
 227 gboolean              gst_structure_id_has_field         (const GstStructure  * structure,
 228                                                           GQuark                field);
 229
 230 gboolean              gst_structure_id_has_field_typed   (const GstStructure  * structure,
 231                                                           GQuark                field,
 232                                                           GType                 type);
 233
 234 gboolean              gst_structure_has_field            (const GstStructure  * structure,
 235                                                           const gchar         * fieldname);
 236
 237 gboolean              gst_structure_has_field_typed      (const GstStructure  * structure,
 238                                                           const gchar         * fieldname,
 239                                                           GType                 type);
 240
 241 /* utility functions */
 242 gboolean              gst_structure_get_boolean          (const GstStructure  * structure,
 243                                                           const gchar         * fieldname,
 244                                                           gboolean            * value);
 245
 246 gboolean              gst_structure_get_int              (const GstStructure  * structure,
 247                                                           const gchar         * fieldname,
 248                                                           gint                * value);
 249
 250 gboolean              gst_structure_get_uint             (const GstStructure  * structure,
 251                                                           const gchar         * fieldname,
 252                                                           guint               * value);
 253
 254 gboolean              gst_structure_get_int64            (const GstStructure  * structure,
 255                                                           const gchar         * fieldname,
 256                                                           gint64              * value);
 257
 258 gboolean              gst_structure_get_uint64           (const GstStructure  * structure,
 259                                                           const gchar         * fieldname,
 260                                                           guint64             * value);
 261
 262 gboolean              gst_structure_get_double           (const GstStructure  * structure,
 263                                                           const gchar         * fieldname,
 264                                                           gdouble             * value);
 265
 266 gboolean              gst_structure_get_date             (const GstStructure  * structure,
 267                                                           const gchar         * fieldname,
 268                                                           GDate              ** value);
 269
 270 gboolean              gst_structure_get_date_time        (const GstStructure  * structure,
 271                                                           const gchar         * fieldname,
 272                                                           GstDateTime        ** value);
 273
 274 gboolean              gst_structure_get_clock_time       (const GstStructure  * structure,
 275                                                           const gchar         * fieldname,
 276                                                           GstClockTime        * value);
 277
 278 const gchar *         gst_structure_get_string           (const GstStructure  * structure,
 279                                                           const gchar         * fieldname);
 280
 281 gboolean              gst_structure_get_enum             (const GstStructure  * structure,
 282                                                           const gchar         * fieldname,
 283                                                           GType                 enumtype,
 284                                                           gint                * value);
 285
 286 gboolean              gst_structure_get_fraction         (const GstStructure  * structure,
 287                                                           const gchar         * fieldname,
 288                                                           gint                * value_numerator,
 289                                                           gint                * value_denominator);
 290
 291 gboolean              gst_structure_get_flagset          (const GstStructure  * structure,
 292                                                           const gchar         * fieldname,
 293                                                           guint               * value_flags,
 294                                                           guint               * value_mask);
 295
 296 gchar *               gst_structure_to_string    (const GstStructure * structure) G_GNUC_MALLOC;
 297
 298 GstStructure *        gst_structure_from_string  (const gchar * string,
 299                                                   gchar      ** end) G_GNUC_MALLOC;
 300
 301 gboolean              gst_structure_fixate_field_nearest_int      (GstStructure * structure,
 302                                                                    const char   * field_name,
 303                                                                    int            target);
 304
 305 gboolean              gst_structure_fixate_field_nearest_double   (GstStructure * structure,
 306                                                                    const char   * field_name,
 307                                                                    double         target);
 308
 309 gboolean              gst_structure_fixate_field_boolean          (GstStructure * structure,
 310                                                                    const char   * field_name,
 311                                                                    gboolean       target);
 312
 313 gboolean              gst_structure_fixate_field_string           (GstStructure * structure,
 314                                                                    const char   * field_name,
 315                                                                    const gchar  * target);
 316
 317 gboolean              gst_structure_fixate_field_nearest_fraction (GstStructure * structure,
 318                                                                    const char   * field_name,
 319                                                                    const gint     target_numerator,
 320                                                                    const gint     target_denominator);
 321
 322 gboolean              gst_structure_fixate_field  (GstStructure * structure,
 323                                                    const char   * field_name);
 324
 325 void                  gst_structure_fixate        (GstStructure * structure);
 326
 327 gboolean              gst_structure_is_equal      (const GstStructure * structure1,
 328                                                    const GstStructure * structure2);
 329
 330 gboolean              gst_structure_is_subset     (const GstStructure * subset,
 331                                                    const GstStructure * superset);
 332
 333 gboolean              gst_structure_can_intersect (const GstStructure * struct1,
 334                                                    const GstStructure * struct2);
 335
 336 GstStructure *        gst_structure_intersect     (const GstStructure * struct1,
 337                                                    const GstStructure * struct2) G_GNUC_MALLOC;
 338
 339 #ifdef G_DEFINE_AUTOPTR_CLEANUP_FUNC
 340 G_DEFINE_AUTOPTR_CLEANUP_FUNC(GstStructure, gst_structure_free)
 341 #endif
 342
 343 G_END_DECLS
 344
 345 #endif
 346