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