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 #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 GST_API
 104 GType                 gst_structure_get_type             (void);
 105
 106 GST_API
 107 GstStructure *        gst_structure_new_empty            (const gchar * name) G_GNUC_MALLOC;
 108
 109 GST_API
 110 GstStructure *        gst_structure_new_id_empty         (GQuark quark) G_GNUC_MALLOC;
 111
 112 GST_API
 113 GstStructure *        gst_structure_new                  (const gchar * name,
 114                                                           const gchar * firstfield,
 115                                                           ...) G_GNUC_NULL_TERMINATED  G_GNUC_MALLOC;
 116 GST_API
 117 GstStructure *        gst_structure_new_valist           (const gchar * name,
 118                                                           const gchar * firstfield,
 119                                                           va_list       varargs) G_GNUC_MALLOC;
 120 GST_API
 121 GstStructure *        gst_structure_new_id               (GQuark name_quark,
 122                                                           GQuark field_quark,
 123                                                           ...) G_GNUC_MALLOC;
 124 GST_API
 125 GstStructure *        gst_structure_new_from_string      (const gchar * string);
 126
 127 GST_API
 128 GstStructure *        gst_structure_copy                 (const GstStructure  * structure) G_GNUC_MALLOC;
 129
 130 GST_API
 131 gboolean              gst_structure_set_parent_refcount  (GstStructure        * structure,
 132                                                           gint                * refcount);
 133 GST_API
 134 void                  gst_structure_free                 (GstStructure        * structure);
 135
 136 GST_API
 137 void                  gst_clear_structure                (GstStructure **structure_ptr);
 138 #define               gst_clear_structure(structure_ptr) g_clear_pointer ((structure_ptr), gst_structure_free)
 139
 140 GST_API
 141 const gchar *         gst_structure_get_name             (const GstStructure  * structure);
 142
 143 GST_API
 144 GQuark                gst_structure_get_name_id          (const GstStructure  * structure);
 145
 146 GST_API
 147 gboolean              gst_structure_has_name             (const GstStructure  * structure,
 148                                                           const gchar         * name);
 149 GST_API
 150 void                  gst_structure_set_name             (GstStructure        * structure,
 151                                                           const gchar         * name);
 152 GST_API
 153 void                  gst_structure_id_set_value         (GstStructure        * structure,
 154                                                           GQuark                field,
 155                                                           const GValue        * value);
 156 GST_API
 157 void                  gst_structure_set_value            (GstStructure        * structure,
 158                                                           const gchar         * fieldname,
 159                                                           const GValue        * value);
 160 GST_API
 161 void                  gst_structure_set_array            (GstStructure        * structure,
 162                                                           const gchar         * fieldname,
 163                                                           const GValueArray   * array);
 164 GST_API
 165 void                  gst_structure_set_list             (GstStructure        * structure,
 166                                                           const gchar         * fieldname,
 167                                                           const GValueArray   * array);
 168 GST_API
 169 void                  gst_structure_id_take_value        (GstStructure        * structure,
 170                                                           GQuark                field,
 171                                                           GValue              * value);
 172 GST_API
 173 void                  gst_structure_take_value           (GstStructure        * structure,
 174                                                           const gchar         * fieldname,
 175                                                           GValue              * value);
 176 GST_API
 177 void                  gst_structure_set                  (GstStructure        * structure,
 178                                                           const gchar         * fieldname,
 179                                                           ...) G_GNUC_NULL_TERMINATED;
 180 GST_API
 181 void                  gst_structure_set_valist           (GstStructure        * structure,
 182                                                           const gchar         * fieldname,
 183                                                           va_list varargs);
 184 GST_API
 185 void                  gst_structure_id_set               (GstStructure        * structure,
 186                                                           GQuark                fieldname,
 187                                                           ...) G_GNUC_NULL_TERMINATED;
 188 GST_API
 189 void                  gst_structure_id_set_valist        (GstStructure        * structure,
 190                                                           GQuark                fieldname,
 191                                                           va_list varargs);
 192 GST_API
 193 gboolean              gst_structure_get_valist           (const GstStructure  * structure,
 194                                                           const char          * first_fieldname,
 195                                                           va_list              args);
 196 GST_API
 197 gboolean              gst_structure_get                  (const GstStructure  * structure,
 198                                                           const char          * first_fieldname,
 199                                                           ...) G_GNUC_NULL_TERMINATED;
 200 GST_API
 201 gboolean              gst_structure_id_get_valist        (const GstStructure  * structure,
 202                                                           GQuark                first_field_id,
 203                                                           va_list               args);
 204 GST_API
 205 gboolean              gst_structure_id_get               (const GstStructure  * structure,
 206                                                           GQuark                first_field_id,
 207                                                           ...) G_GNUC_NULL_TERMINATED;
 208 GST_API
 209 const GValue *        gst_structure_id_get_value         (const GstStructure  * structure,
 210                                                           GQuark                field);
 211 GST_API
 212 const GValue *        gst_structure_get_value            (const GstStructure  * structure,
 213                                                           const gchar         * fieldname);
 214 GST_API
 215 void                  gst_structure_remove_field         (GstStructure        * structure,
 216                                                           const gchar         * fieldname);
 217 GST_API
 218 void                  gst_structure_remove_fields        (GstStructure        * structure,
 219                                                           const gchar         * fieldname,
 220                                                           ...) G_GNUC_NULL_TERMINATED;
 221 GST_API
 222 void                  gst_structure_remove_fields_valist (GstStructure        * structure,
 223                                                           const gchar         * fieldname,
 224                                                           va_list               varargs);
 225 GST_API
 226 void                  gst_structure_remove_all_fields    (GstStructure        * structure);
 227
 228 GST_API
 229 GType                 gst_structure_get_field_type       (const GstStructure  * structure,
 230                                                           const gchar         * fieldname);
 231 GST_API
 232 gboolean              gst_structure_foreach              (const GstStructure  * structure,
 233                                                           GstStructureForeachFunc   func,
 234                                                           gpointer              user_data);
 235 GST_API
 236 gboolean              gst_structure_map_in_place         (GstStructure        * structure,
 237                                                           GstStructureMapFunc   func,
 238                                                           gpointer              user_data);
 239 GST_API
 240 void                  gst_structure_filter_and_map_in_place (GstStructure        * structure,
 241                                                           GstStructureFilterMapFunc   func,
 242                                                           gpointer              user_data);
 243 GST_API
 244 gint                  gst_structure_n_fields             (const GstStructure  * structure);
 245
 246 GST_API
 247 const gchar *         gst_structure_nth_field_name       (const GstStructure  * structure,
 248                                                           guint                 index);
 249 GST_API
 250 gboolean              gst_structure_id_has_field         (const GstStructure  * structure,
 251                                                           GQuark                field);
 252 GST_API
 253 gboolean              gst_structure_id_has_field_typed   (const GstStructure  * structure,
 254                                                           GQuark                field,
 255                                                           GType                 type);
 256 GST_API
 257 gboolean              gst_structure_has_field            (const GstStructure  * structure,
 258                                                           const gchar         * fieldname);
 259 GST_API
 260 gboolean              gst_structure_has_field_typed      (const GstStructure  * structure,
 261                                                           const gchar         * fieldname,
 262                                                           GType                 type);
 263
 264 /* utility functions */
 265
 266 GST_API
 267 gboolean              gst_structure_get_boolean          (const GstStructure  * structure,
 268                                                           const gchar         * fieldname,
 269                                                           gboolean            * value);
 270 GST_API
 271 gboolean              gst_structure_get_int              (const GstStructure  * structure,
 272                                                           const gchar         * fieldname,
 273                                                           gint                * value);
 274 GST_API
 275 gboolean              gst_structure_get_uint             (const GstStructure  * structure,
 276                                                           const gchar         * fieldname,
 277                                                           guint               * value);
 278 GST_API
 279 gboolean              gst_structure_get_int64            (const GstStructure  * structure,
 280                                                           const gchar         * fieldname,
 281                                                           gint64              * value);
 282 GST_API
 283 gboolean              gst_structure_get_uint64           (const GstStructure  * structure,
 284                                                           const gchar         * fieldname,
 285                                                           guint64             * value);
 286 GST_API
 287 gboolean              gst_structure_get_double           (const GstStructure  * structure,
 288                                                           const gchar         * fieldname,
 289                                                           gdouble             * value);
 290 GST_API
 291 gboolean              gst_structure_get_date             (const GstStructure  * structure,
 292                                                           const gchar         * fieldname,
 293                                                           GDate              ** value);
 294 GST_API
 295 gboolean              gst_structure_get_date_time        (const GstStructure  * structure,
 296                                                           const gchar         * fieldname,
 297                                                           GstDateTime        ** value);
 298 GST_API
 299 gboolean              gst_structure_get_clock_time       (const GstStructure  * structure,
 300                                                           const gchar         * fieldname,
 301                                                           GstClockTime        * value);
 302 GST_API
 303 const gchar *         gst_structure_get_string           (const GstStructure  * structure,
 304                                                           const gchar         * fieldname);
 305 GST_API
 306 gboolean              gst_structure_get_enum             (const GstStructure  * structure,
 307                                                           const gchar         * fieldname,
 308                                                           GType                 enumtype,
 309                                                           gint                * value);
 310 GST_API
 311 gboolean              gst_structure_get_fraction         (const GstStructure  * structure,
 312                                                           const gchar         * fieldname,
 313                                                           gint                * value_numerator,
 314                                                           gint                * value_denominator);
 315 GST_API
 316 gboolean              gst_structure_get_flagset          (const GstStructure  * structure,
 317                                                           const gchar         * fieldname,
 318                                                           guint               * value_flags,
 319                                                           guint               * value_mask);
 320 GST_API
 321 gboolean              gst_structure_get_array            (GstStructure        * structure,
 322                                                           const gchar         * fieldname,
 323                                                           GValueArray        ** array);
 324 GST_API
 325 gboolean              gst_structure_get_list             (GstStructure        * structure,
 326                                                           const gchar         * fieldname,
 327                                                           GValueArray        ** array);
 328 GST_API
 329 gchar *               gst_structure_to_string    (const GstStructure * structure) G_GNUC_MALLOC;
 330
 331 GST_API
 332 GstStructure *        gst_structure_from_string  (const gchar * string,
 333                                                   gchar      ** end) G_GNUC_MALLOC;
 334 GST_API
 335 gboolean              gst_structure_fixate_field_nearest_int      (GstStructure * structure,
 336                                                                    const char   * field_name,
 337                                                                    int            target);
 338 GST_API
 339 gboolean              gst_structure_fixate_field_nearest_double   (GstStructure * structure,
 340                                                                    const char   * field_name,
 341                                                                    double         target);
 342 GST_API
 343 gboolean              gst_structure_fixate_field_boolean          (GstStructure * structure,
 344                                                                    const char   * field_name,
 345                                                                    gboolean       target);
 346 GST_API
 347 gboolean              gst_structure_fixate_field_string           (GstStructure * structure,
 348                                                                    const char   * field_name,
 349                                                                    const gchar  * target);
 350 GST_API
 351 gboolean              gst_structure_fixate_field_nearest_fraction (GstStructure * structure,
 352                                                                    const char   * field_name,
 353                                                                    const gint     target_numerator,
 354                                                                    const gint     target_denominator);
 355 GST_API
 356 gboolean              gst_structure_fixate_field  (GstStructure * structure,
 357                                                    const char   * field_name);
 358 GST_API
 359 void                  gst_structure_fixate        (GstStructure * structure);
 360
 361 GST_API
 362 gboolean              gst_structure_is_equal      (const GstStructure * structure1,
 363                                                    const GstStructure * structure2);
 364 GST_API
 365 gboolean              gst_structure_is_subset     (const GstStructure * subset,
 366                                                    const GstStructure * superset);
 367 GST_API
 368 gboolean              gst_structure_can_intersect (const GstStructure * struct1,
 369                                                    const GstStructure * struct2);
 370 GST_API
 371 GstStructure *        gst_structure_intersect     (const GstStructure * struct1,
 372                                                    const GstStructure * struct2) G_GNUC_MALLOC;
 373
 374 #ifdef G_DEFINE_AUTOPTR_CLEANUP_FUNC
 375 G_DEFINE_AUTOPTR_CLEANUP_FUNC(GstStructure, gst_structure_free)
 376 #endif
 377
 378 G_END_DECLS
 379
 380 #endif
 381