subprojects/gstreamer/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_API GType _gst_structure_type;
  32
  33 typedef struct _GstStructure GstStructure;
  34
  35 /**
  36  * GstSerializeFlags:
  37  * @GST_SERIALIZE_FLAG_NONE: No special flags specified.
  38  * @GST_SERIALIZE_FLAG_BACKWARD_COMPAT: Serialize using the old format for
  39  *                                      nested structures.
  40  *
  41  * Since: 1.20
  42  */
  43 typedef enum
  44 {
  45   GST_SERIALIZE_FLAG_NONE = 0,
  46   GST_SERIALIZE_FLAG_BACKWARD_COMPAT = (1 << 0),
  47 } GstSerializeFlags;
  48
  49 #define GST_TYPE_STRUCTURE             (_gst_structure_type)
  50 #define GST_IS_STRUCTURE(object)       ((object) && (GST_STRUCTURE(object)->type == GST_TYPE_STRUCTURE))
  51 #define GST_STRUCTURE_CAST(object)     ((GstStructure *)(object))
  52 #define GST_STRUCTURE(object)          (GST_STRUCTURE_CAST(object))
  53
  54
  55 /**
  56  * GstStructureForeachFunc:
  57  * @field_id: the #GQuark of the field name
  58  * @value: the #GValue of the field
  59  * @user_data: user data
  60  *
  61  * A function that will be called in gst_structure_foreach(). The function may
  62  * not modify @value.
  63  *
  64  * Returns: %TRUE if the foreach operation should continue, %FALSE if
  65  * the foreach operation should stop with %FALSE.
  66  */
  67 typedef gboolean (*GstStructureForeachFunc) (GQuark   field_id,
  68                                              const GValue * value,
  69                                              gpointer user_data);
  70
  71 /**
  72  * GstStructureMapFunc:
  73  * @field_id: the #GQuark of the field name
  74  * @value: the #GValue of the field
  75  * @user_data: user data
  76  *
  77  * A function that will be called in gst_structure_map_in_place(). The function
  78  * may modify @value.
  79  *
  80  * Returns: %TRUE if the map operation should continue, %FALSE if
  81  * the map operation should stop with %FALSE.
  82  */
  83 typedef gboolean (*GstStructureMapFunc)     (GQuark   field_id,
  84                                              GValue * value,
  85                                              gpointer user_data);
  86
  87 /**
  88  * GstStructureFilterMapFunc:
  89  * @field_id: the #GQuark of the field name
  90  * @value: the #GValue of the field
  91  * @user_data: user data
  92  *
  93  * A function that will be called in gst_structure_filter_and_map_in_place().
  94  * The function may modify @value, and the value will be removed from
  95  * the structure if %FALSE is returned.
  96  *
  97  * Returns: %TRUE if the field should be preserved, %FALSE if it
  98  * should be removed.
  99  */
 100 typedef gboolean (*GstStructureFilterMapFunc) (GQuark   field_id,
 101                                                GValue * value,
 102                                                gpointer user_data);
 103
 104 /**
 105  * GstStructure:
 106  * @type: the GType of a structure
 107  *
 108  * The GstStructure object. Most fields are private.
 109  */
 110 struct _GstStructure {
 111   GType type;
 112
 113   /*< private >*/
 114   GQuark name;
 115 };
 116
 117 GST_API
 118 GType                 gst_structure_get_type             (void);
 119
 120 GST_API
 121 GstStructure *        gst_structure_new_empty            (const gchar * name) G_GNUC_MALLOC;
 122
 123 GST_API
 124 GstStructure *        gst_structure_new_id_empty         (GQuark quark) G_GNUC_MALLOC;
 125
 126 GST_API
 127 GstStructure *        gst_structure_new                  (const gchar * name,
 128                                                           const gchar * firstfield,
 129                                                           ...) G_GNUC_NULL_TERMINATED  G_GNUC_MALLOC;
 130 GST_API
 131 GstStructure *        gst_structure_new_valist           (const gchar * name,
 132                                                           const gchar * firstfield,
 133                                                           va_list       varargs) G_GNUC_MALLOC;
 134 GST_API
 135 GstStructure *        gst_structure_new_id               (GQuark name_quark,
 136                                                           GQuark field_quark,
 137                                                           ...) G_GNUC_MALLOC;
 138 GST_API
 139 GstStructure *        gst_structure_new_from_string      (const gchar * string);
 140
 141 GST_API
 142 GstStructure *        gst_structure_copy                 (const GstStructure  * structure) G_GNUC_MALLOC;
 143
 144 GST_API
 145 gboolean              gst_structure_set_parent_refcount  (GstStructure        * structure,
 146                                                           gint                * refcount);
 147 GST_API
 148 void                  gst_structure_free                 (GstStructure        * structure);
 149
 150 GST_API
 151 void                  gst_clear_structure                (GstStructure **structure_ptr);
 152 #define               gst_clear_structure(structure_ptr) g_clear_pointer ((structure_ptr), gst_structure_free)
 153
 154 GST_API
 155 gboolean              gst_structure_take                 (GstStructure ** oldstr_ptr,
 156                                                           GstStructure * newstr);
 157 GST_API
 158 const gchar *         gst_structure_get_name             (const GstStructure  * structure);
 159
 160 GST_API
 161 GQuark                gst_structure_get_name_id          (const GstStructure  * structure);
 162
 163 GST_API
 164 gboolean              gst_structure_has_name             (const GstStructure  * structure,
 165                                                           const gchar         * name);
 166 GST_API
 167 void                  gst_structure_set_name             (GstStructure        * structure,
 168                                                           const gchar         * name);
 169 GST_API
 170 void                  gst_structure_id_set_value         (GstStructure        * structure,
 171                                                           GQuark                field,
 172                                                           const GValue        * value);
 173 GST_API
 174 void                  gst_structure_set_value            (GstStructure        * structure,
 175                                                           const gchar         * fieldname,
 176                                                           const GValue        * value);
 177 GST_API
 178 void                  gst_structure_set_array            (GstStructure        * structure,
 179                                                           const gchar         * fieldname,
 180                                                           const GValueArray   * array);
 181 GST_API
 182 void                  gst_structure_set_list             (GstStructure        * structure,
 183                                                           const gchar         * fieldname,
 184                                                           const GValueArray   * array);
 185 GST_API
 186 void                  gst_structure_id_take_value        (GstStructure        * structure,
 187                                                           GQuark                field,
 188                                                           GValue              * value);
 189 GST_API
 190 void                  gst_structure_take_value           (GstStructure        * structure,
 191                                                           const gchar         * fieldname,
 192                                                           GValue              * value);
 193 GST_API
 194 void                  gst_structure_set                  (GstStructure        * structure,
 195                                                           const gchar         * fieldname,
 196                                                           ...) G_GNUC_NULL_TERMINATED;
 197 GST_API
 198 void                  gst_structure_set_valist           (GstStructure        * structure,
 199                                                           const gchar         * fieldname,
 200                                                           va_list varargs);
 201 GST_API
 202 void                  gst_structure_id_set               (GstStructure        * structure,
 203                                                           GQuark                fieldname,
 204                                                           ...) G_GNUC_NULL_TERMINATED;
 205 GST_API
 206 void                  gst_structure_id_set_valist        (GstStructure        * structure,
 207                                                           GQuark                fieldname,
 208                                                           va_list varargs);
 209 GST_API
 210 gboolean              gst_structure_get_valist           (const GstStructure  * structure,
 211                                                           const char          * first_fieldname,
 212                                                           va_list              args);
 213 GST_API
 214 gboolean              gst_structure_get                  (const GstStructure  * structure,
 215                                                           const char          * first_fieldname,
 216                                                           ...) G_GNUC_NULL_TERMINATED;
 217 GST_API
 218 gboolean              gst_structure_id_get_valist        (const GstStructure  * structure,
 219                                                           GQuark                first_field_id,
 220                                                           va_list               args);
 221 GST_API
 222 gboolean              gst_structure_id_get               (const GstStructure  * structure,
 223                                                           GQuark                first_field_id,
 224                                                           ...) G_GNUC_NULL_TERMINATED;
 225 GST_API
 226 const GValue *        gst_structure_id_get_value         (const GstStructure  * structure,
 227                                                           GQuark                field);
 228 GST_API
 229 const GValue *        gst_structure_get_value            (const GstStructure  * structure,
 230                                                           const gchar         * fieldname);
 231 GST_API
 232 void                  gst_structure_remove_field         (GstStructure        * structure,
 233                                                           const gchar         * fieldname);
 234 GST_API
 235 void                  gst_structure_remove_fields        (GstStructure        * structure,
 236                                                           const gchar         * fieldname,
 237                                                           ...) G_GNUC_NULL_TERMINATED;
 238 GST_API
 239 void                  gst_structure_remove_fields_valist (GstStructure        * structure,
 240                                                           const gchar         * fieldname,
 241                                                           va_list               varargs);
 242 GST_API
 243 void                  gst_structure_remove_all_fields    (GstStructure        * structure);
 244
 245 GST_API
 246 GType                 gst_structure_get_field_type       (const GstStructure  * structure,
 247                                                           const gchar         * fieldname);
 248 GST_API
 249 gboolean              gst_structure_foreach              (const GstStructure  * structure,
 250                                                           GstStructureForeachFunc   func,
 251                                                           gpointer              user_data);
 252 GST_API
 253 gboolean              gst_structure_map_in_place         (GstStructure        * structure,
 254                                                           GstStructureMapFunc   func,
 255                                                           gpointer              user_data);
 256 GST_API
 257 void                  gst_structure_filter_and_map_in_place (GstStructure        * structure,
 258                                                           GstStructureFilterMapFunc   func,
 259                                                           gpointer              user_data);
 260 GST_API
 261 gint                  gst_structure_n_fields             (const GstStructure  * structure);
 262
 263 GST_API
 264 const gchar *         gst_structure_nth_field_name       (const GstStructure  * structure,
 265                                                           guint                 index);
 266 GST_API
 267 gboolean              gst_structure_id_has_field         (const GstStructure  * structure,
 268                                                           GQuark                field);
 269 GST_API
 270 gboolean              gst_structure_id_has_field_typed   (const GstStructure  * structure,
 271                                                           GQuark                field,
 272                                                           GType                 type);
 273 GST_API
 274 gboolean              gst_structure_has_field            (const GstStructure  * structure,
 275                                                           const gchar         * fieldname);
 276 GST_API
 277 gboolean              gst_structure_has_field_typed      (const GstStructure  * structure,
 278                                                           const gchar         * fieldname,
 279                                                           GType                 type);
 280
 281 /* utility functions */
 282
 283 GST_API
 284 gboolean              gst_structure_get_boolean          (const GstStructure  * structure,
 285                                                           const gchar         * fieldname,
 286                                                           gboolean            * value);
 287 GST_API
 288 gboolean              gst_structure_get_int              (const GstStructure  * structure,
 289                                                           const gchar         * fieldname,
 290                                                           gint                * value);
 291 GST_API
 292 gboolean              gst_structure_get_uint             (const GstStructure  * structure,
 293                                                           const gchar         * fieldname,
 294                                                           guint               * value);
 295 GST_API
 296 gboolean              gst_structure_get_int64            (const GstStructure  * structure,
 297                                                           const gchar         * fieldname,
 298                                                           gint64              * value);
 299 GST_API
 300 gboolean              gst_structure_get_uint64           (const GstStructure  * structure,
 301                                                           const gchar         * fieldname,
 302                                                           guint64             * value);
 303 GST_API
 304 gboolean              gst_structure_get_double           (const GstStructure  * structure,
 305                                                           const gchar         * fieldname,
 306                                                           gdouble             * value);
 307 GST_API
 308 gboolean              gst_structure_get_date             (const GstStructure  * structure,
 309                                                           const gchar         * fieldname,
 310                                                           GDate              ** value);
 311 GST_API
 312 gboolean              gst_structure_get_date_time        (const GstStructure  * structure,
 313                                                           const gchar         * fieldname,
 314                                                           GstDateTime        ** value);
 315 GST_API
 316 gboolean              gst_structure_get_clock_time       (const GstStructure  * structure,
 317                                                           const gchar         * fieldname,
 318                                                           GstClockTime        * value);
 319 GST_API
 320 const gchar *         gst_structure_get_string           (const GstStructure  * structure,
 321                                                           const gchar         * fieldname);
 322 GST_API
 323 gboolean              gst_structure_get_enum             (const GstStructure  * structure,
 324                                                           const gchar         * fieldname,
 325                                                           GType                 enumtype,
 326                                                           gint                * value);
 327 GST_API
 328 gboolean              gst_structure_get_fraction         (const GstStructure  * structure,
 329                                                           const gchar         * fieldname,
 330                                                           gint                * value_numerator,
 331                                                           gint                * value_denominator);
 332 GST_API
 333 gboolean              gst_structure_get_flagset          (const GstStructure  * structure,
 334                                                           const gchar         * fieldname,
 335                                                           guint               * value_flags,
 336                                                           guint               * value_mask);
 337 GST_API
 338 gboolean              gst_structure_get_array            (GstStructure        * structure,
 339                                                           const gchar         * fieldname,
 340                                                           GValueArray        ** array);
 341 GST_API
 342 gboolean              gst_structure_get_list             (GstStructure        * structure,
 343                                                           const gchar         * fieldname,
 344                                                           GValueArray        ** array);
 345 GST_API
 346 gchar *               gst_structure_to_string            (const GstStructure * structure) G_GNUC_MALLOC;
 347 GST_API
 348 gchar *               gst_structure_serialize            (const GstStructure * structure,
 349                                                           GstSerializeFlags flags) G_GNUC_MALLOC;
 350
 351 GST_API
 352 GstStructure *        gst_structure_from_string  (const gchar * string,
 353                                                   gchar      ** end) G_GNUC_MALLOC;
 354 GST_API
 355 gboolean              gst_structure_fixate_field_nearest_int      (GstStructure * structure,
 356                                                                    const char   * field_name,
 357                                                                    int            target);
 358 GST_API
 359 gboolean              gst_structure_fixate_field_nearest_double   (GstStructure * structure,
 360                                                                    const char   * field_name,
 361                                                                    double         target);
 362 GST_API
 363 gboolean              gst_structure_fixate_field_boolean          (GstStructure * structure,
 364                                                                    const char   * field_name,
 365                                                                    gboolean       target);
 366 GST_API
 367 gboolean              gst_structure_fixate_field_string           (GstStructure * structure,
 368                                                                    const char   * field_name,
 369                                                                    const gchar  * target);
 370 GST_API
 371 gboolean              gst_structure_fixate_field_nearest_fraction (GstStructure * structure,
 372                                                                    const char   * field_name,
 373                                                                    const gint     target_numerator,
 374                                                                    const gint     target_denominator);
 375 GST_API
 376 gboolean              gst_structure_fixate_field  (GstStructure * structure,
 377                                                    const char   * field_name);
 378 GST_API
 379 void                  gst_structure_fixate        (GstStructure * structure);
 380
 381 GST_API
 382 gboolean              gst_structure_is_equal      (const GstStructure * structure1,
 383                                                    const GstStructure * structure2);
 384 GST_API
 385 gboolean              gst_structure_is_subset     (const GstStructure * subset,
 386                                                    const GstStructure * superset);
 387 GST_API
 388 gboolean              gst_structure_can_intersect (const GstStructure * struct1,
 389                                                    const GstStructure * struct2);
 390 GST_API
 391 GstStructure *        gst_structure_intersect     (const GstStructure * struct1,
 392                                                    const GstStructure * struct2) G_GNUC_MALLOC;
 393
 394 G_DEFINE_AUTOPTR_CLEANUP_FUNC(GstStructure, gst_structure_free)
 395
 396 G_END_DECLS
 397
 398 #endif
 399