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  * GstStructure:
  75  * @type: the GType of a structure
  76  *
  77  * The GstStructure object. Most fields are private.
  78  */
  79 struct _GstStructure {
  80   GType type;
  81
  82   /*< private >*/
  83   GQuark name;
  84 };
  85
  86 GType                 gst_structure_get_type             (void);
  87
  88 GstStructure *        gst_structure_new_empty            (const gchar * name) G_GNUC_MALLOC;
  89
  90 GstStructure *        gst_structure_new_id_empty         (GQuark quark) G_GNUC_MALLOC;
  91
  92 GstStructure *        gst_structure_new                  (const gchar * name,
  93                                                           const gchar * firstfield,
  94                                                           ...) G_GNUC_NULL_TERMINATED  G_GNUC_MALLOC;
  95
  96 GstStructure *        gst_structure_new_valist           (const gchar * name,
  97                                                           const gchar * firstfield,
  98                                                           va_list       varargs) G_GNUC_MALLOC;
  99
 100 GstStructure *        gst_structure_new_id               (GQuark name_quark,
 101                                                           GQuark field_quark,
 102                                                           ...) G_GNUC_MALLOC;
 103
 104 GstStructure *        gst_structure_copy                 (const GstStructure  * structure) G_GNUC_MALLOC;
 105
 106 gboolean              gst_structure_set_parent_refcount  (GstStructure        * structure,
 107                                                             gint                * refcount);
 108
 109 void                  gst_structure_free                 (GstStructure        * structure);
 110
 111 const gchar *         gst_structure_get_name             (const GstStructure  * structure);
 112
 113 GQuark                gst_structure_get_name_id          (const GstStructure  * structure);
 114
 115 gboolean              gst_structure_has_name             (const GstStructure  * structure,
 116                                                           const gchar         * name);
 117
 118 void                  gst_structure_set_name             (GstStructure        * structure,
 119                                                           const gchar         * name);
 120
 121 void                  gst_structure_id_set_value         (GstStructure        * structure,
 122                                                           GQuark                field,
 123                                                           const GValue        * value);
 124
 125 void                  gst_structure_set_value            (GstStructure        * structure,
 126                                                           const gchar         * fieldname,
 127                                                           const GValue        * value);
 128
 129 void                  gst_structure_id_take_value        (GstStructure        * structure,
 130                                                           GQuark                field,
 131                                                           GValue              * value);
 132
 133 void                  gst_structure_take_value           (GstStructure        * structure,
 134                                                           const gchar         * fieldname,
 135                                                           GValue              * value);
 136
 137 void                  gst_structure_set                  (GstStructure        * structure,
 138                                                           const gchar         * fieldname,
 139                                                           ...) G_GNUC_NULL_TERMINATED;
 140
 141 void                  gst_structure_set_valist           (GstStructure        * structure,
 142                                                           const gchar         * fieldname,
 143                                                           va_list varargs);
 144
 145 void                  gst_structure_id_set               (GstStructure        * structure,
 146                                                           GQuark                fieldname,
 147                                                           ...) G_GNUC_NULL_TERMINATED;
 148
 149 void                  gst_structure_id_set_valist        (GstStructure        * structure,
 150                                                           GQuark                fieldname,
 151                                                           va_list varargs);
 152
 153 gboolean              gst_structure_get_valist           (const GstStructure  * structure,
 154                                                           const char          * first_fieldname,
 155                                                           va_list              args);
 156
 157 gboolean              gst_structure_get                  (const GstStructure  * structure,
 158                                                           const char          * first_fieldname,
 159                                                           ...) G_GNUC_NULL_TERMINATED;
 160
 161 gboolean              gst_structure_id_get_valist        (const GstStructure  * structure,
 162                                                           GQuark                first_field_id,
 163                                                           va_list               args);
 164
 165 gboolean              gst_structure_id_get               (const GstStructure  * structure,
 166                                                           GQuark                first_field_id,
 167                                                           ...) G_GNUC_NULL_TERMINATED;
 168
 169 const GValue *        gst_structure_id_get_value         (const GstStructure  * structure,
 170                                                           GQuark                field);
 171
 172 const GValue *        gst_structure_get_value            (const GstStructure  * structure,
 173                                                           const gchar         * fieldname);
 174
 175 void                  gst_structure_remove_field         (GstStructure        * structure,
 176                                                             const gchar         * fieldname);
 177
 178 void                  gst_structure_remove_fields        (GstStructure        * structure,
 179                                                           const gchar         * fieldname,
 180                                                           ...) G_GNUC_NULL_TERMINATED;
 181
 182 void                  gst_structure_remove_fields_valist (GstStructure        * structure,
 183                                                           const gchar         * fieldname,
 184                                                           va_list               varargs);
 185
 186 void                  gst_structure_remove_all_fields    (GstStructure        * structure);
 187
 188 GType                 gst_structure_get_field_type       (const GstStructure  * structure,
 189                                                           const gchar         * fieldname);
 190
 191 gboolean              gst_structure_foreach              (const GstStructure  * structure,
 192                                                           GstStructureForeachFunc   func,
 193                                                           gpointer              user_data);
 194
 195 gboolean              gst_structure_map_in_place         (GstStructure        * structure,
 196                                                           GstStructureMapFunc   func,
 197                                                           gpointer              user_data);
 198
 199 gint                  gst_structure_n_fields             (const GstStructure  * structure);
 200
 201 const gchar *         gst_structure_nth_field_name       (const GstStructure  * structure,
 202                                                           guint                 index);
 203
 204 gboolean              gst_structure_id_has_field         (const GstStructure  * structure,
 205                                                           GQuark                field);
 206
 207 gboolean              gst_structure_id_has_field_typed   (const GstStructure  * structure,
 208                                                           GQuark                field,
 209                                                           GType                 type);
 210
 211 gboolean              gst_structure_has_field            (const GstStructure  * structure,
 212                                                           const gchar         * fieldname);
 213
 214 gboolean              gst_structure_has_field_typed      (const GstStructure  * structure,
 215                                                           const gchar         * fieldname,
 216                                                           GType                 type);
 217
 218 /* utility functions */
 219 gboolean              gst_structure_get_boolean          (const GstStructure  * structure,
 220                                                           const gchar         * fieldname,
 221                                                           gboolean            * value);
 222
 223 gboolean              gst_structure_get_int              (const GstStructure  * structure,
 224                                                           const gchar         * fieldname,
 225                                                           gint                * value);
 226
 227 gboolean              gst_structure_get_uint             (const GstStructure  * structure,
 228                                                           const gchar         * fieldname,
 229                                                           guint               * value);
 230
 231 gboolean              gst_structure_get_double           (const GstStructure  * structure,
 232                                                           const gchar         * fieldname,
 233                                                           gdouble             * value);
 234
 235 gboolean              gst_structure_get_date             (const GstStructure  * structure,
 236                                                           const gchar         * fieldname,
 237                                                           GDate              ** value);
 238
 239 gboolean              gst_structure_get_date_time        (const GstStructure  * structure,
 240                                                           const gchar         * fieldname,
 241                                                           GstDateTime        ** value);
 242
 243 gboolean              gst_structure_get_clock_time       (const GstStructure  * structure,
 244                                                           const gchar         * fieldname,
 245                                                           GstClockTime        * value);
 246
 247 const gchar *         gst_structure_get_string           (const GstStructure  * structure,
 248                                                           const gchar         * fieldname);
 249
 250 gboolean              gst_structure_get_enum             (const GstStructure  * structure,
 251                                                           const gchar         * fieldname,
 252                                                           GType                 enumtype,
 253                                                           gint                * value);
 254
 255 gboolean              gst_structure_get_fraction         (const GstStructure  * structure,
 256                                                           const gchar         * fieldname,
 257                                                           gint                * value_numerator,
 258                                                           gint                * value_denominator);
 259
 260 gchar *               gst_structure_to_string    (const GstStructure * structure) G_GNUC_MALLOC;
 261
 262 GstStructure *        gst_structure_from_string  (const gchar * string,
 263                                                   gchar      ** end) G_GNUC_MALLOC;
 264
 265 gboolean              gst_structure_fixate_field_nearest_int      (GstStructure * structure,
 266                                                                    const char   * field_name,
 267                                                                    int            target);
 268
 269 gboolean              gst_structure_fixate_field_nearest_double   (GstStructure * structure,
 270                                                                    const char   * field_name,
 271                                                                    double         target);
 272
 273 gboolean              gst_structure_fixate_field_boolean          (GstStructure * structure,
 274                                                                    const char   * field_name,
 275                                                                    gboolean       target);
 276
 277 gboolean              gst_structure_fixate_field_string           (GstStructure * structure,
 278                                                                    const char   * field_name,
 279                                                                    const gchar  * target);
 280
 281 gboolean              gst_structure_fixate_field_nearest_fraction (GstStructure * structure,
 282                                                                    const char   * field_name,
 283                                                                    const gint     target_numerator,
 284                                                                    const gint     target_denominator);
 285
 286 gboolean              gst_structure_fixate_field  (GstStructure * structure,
 287                                                    const char   * field_name);
 288
 289 void                  gst_structure_fixate        (GstStructure * structure);
 290
 291 gboolean              gst_structure_is_equal      (const GstStructure * structure1,
 292                                                    const GstStructure * structure2);
 293
 294 gboolean              gst_structure_is_subset     (const GstStructure * subset,
 295                                                    const GstStructure * superset);
 296
 297 gboolean              gst_structure_can_intersect (const GstStructure * struct1,
 298                                                    const GstStructure * struct2);
 299
 300 GstStructure *        gst_structure_intersect     (const GstStructure * struct1,
 301                                                    const GstStructure * struct2) G_GNUC_MALLOC;
 302
 303 G_END_DECLS
 304
 305 #endif
 306