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., 59 Temple Place - Suite 330,
  17  * Boston, MA 02111-1307, 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 GstStructure *          gst_structure_new_id_empty         (GQuark                   quark) G_GNUC_MALLOC;
  90 GstStructure *          gst_structure_new                  (const gchar *            name,
  91                                                             const gchar *            firstfield,
  92                                                             ...) G_GNUC_NULL_TERMINATED  G_GNUC_MALLOC;
  93 GstStructure *          gst_structure_new_valist           (const gchar *            name,
  94                                                             const gchar *            firstfield,
  95                                                             va_list                  varargs) G_GNUC_MALLOC;
  96 GstStructure *          gst_structure_new_id               (GQuark                   name_quark,
  97                                                             GQuark                   field_quark,
  98                                                             ...) G_GNUC_MALLOC;
  99 GstStructure *          gst_structure_copy                 (const GstStructure      *structure) G_GNUC_MALLOC;
 100 gboolean                gst_structure_set_parent_refcount  (GstStructure            *structure,
 101                                                             gint                    *refcount);
 102 void                    gst_structure_free                 (GstStructure            *structure);
 103
 104 const gchar *           gst_structure_get_name             (const GstStructure      *structure);
 105 GQuark                  gst_structure_get_name_id          (const GstStructure      *structure);
 106 gboolean                gst_structure_has_name             (const GstStructure      *structure,
 107                                                             const gchar             *name);
 108 void                    gst_structure_set_name             (GstStructure            *structure,
 109                                                             const gchar             *name);
 110
 111 void                    gst_structure_id_set_value         (GstStructure            *structure,
 112                                                             GQuark                   field,
 113                                                             const GValue            *value);
 114 void                    gst_structure_set_value            (GstStructure            *structure,
 115                                                             const gchar             *fieldname,
 116                                                             const GValue            *value);
 117 void                    gst_structure_id_take_value         (GstStructure            *structure,
 118                                                             GQuark                   field,
 119                                                             GValue                  *value);
 120 void                    gst_structure_take_value            (GstStructure            *structure,
 121                                                             const gchar             *fieldname,
 122                                                             GValue                  *value);
 123 void                    gst_structure_set                  (GstStructure            *structure,
 124                                                             const gchar             *fieldname,
 125                                                             ...) G_GNUC_NULL_TERMINATED;
 126
 127 void                    gst_structure_set_valist           (GstStructure            *structure,
 128                                                             const gchar             *fieldname,
 129                                                             va_list varargs);
 130
 131 void                    gst_structure_id_set                (GstStructure            *structure,
 132                                                             GQuark                   fieldname,
 133                                                             ...) G_GNUC_NULL_TERMINATED;
 134
 135 void                    gst_structure_id_set_valist         (GstStructure            *structure,
 136                                                             GQuark                   fieldname,
 137                                                             va_list varargs);
 138
 139 gboolean                gst_structure_get_valist           (const GstStructure      *structure,
 140                                                             const char              *first_fieldname,
 141                                                             va_list                  args);
 142
 143 gboolean                gst_structure_get                  (const GstStructure      *structure,
 144                                                             const char              *first_fieldname,
 145                                                             ...) G_GNUC_NULL_TERMINATED;
 146
 147 gboolean                gst_structure_id_get_valist        (const GstStructure      *structure,
 148                                                             GQuark                   first_field_id,
 149                                                             va_list                  args);
 150
 151 gboolean                gst_structure_id_get               (const GstStructure      *structure,
 152                                                             GQuark                   first_field_id,
 153                                                             ...) G_GNUC_NULL_TERMINATED;
 154
 155 const GValue *          gst_structure_id_get_value         (const GstStructure      *structure,
 156                                                             GQuark                   field);
 157 const GValue *          gst_structure_get_value            (const GstStructure      *structure,
 158                                                             const gchar             *fieldname);
 159 void                    gst_structure_remove_field         (GstStructure            *structure,
 160                                                             const gchar             *fieldname);
 161 void                    gst_structure_remove_fields        (GstStructure            *structure,
 162                                                              const gchar            *fieldname,
 163                                                             ...) G_GNUC_NULL_TERMINATED;
 164 void                    gst_structure_remove_fields_valist (GstStructure             *structure,
 165                                                             const gchar             *fieldname,
 166                                                             va_list                  varargs);
 167 void                    gst_structure_remove_all_fields    (GstStructure            *structure);
 168
 169 GType                   gst_structure_get_field_type       (const GstStructure      *structure,
 170                                                             const gchar             *fieldname);
 171 gboolean                gst_structure_foreach              (const GstStructure      *structure,
 172                                                             GstStructureForeachFunc  func,
 173                                                             gpointer                 user_data);
 174 gboolean                gst_structure_map_in_place         (GstStructure            *structure,
 175                                                             GstStructureMapFunc      func,
 176                                                             gpointer                 user_data);
 177 gint                    gst_structure_n_fields             (const GstStructure      *structure);
 178 const gchar *           gst_structure_nth_field_name       (const GstStructure      *structure, guint index);
 179 gboolean                gst_structure_id_has_field         (const GstStructure      *structure,
 180                                                             GQuark                   field);
 181 gboolean                gst_structure_id_has_field_typed   (const GstStructure      *structure,
 182                                                             GQuark                   field,
 183                                                             GType                    type);
 184 gboolean                gst_structure_has_field            (const GstStructure      *structure,
 185                                                             const gchar             *fieldname);
 186 gboolean                gst_structure_has_field_typed      (const GstStructure      *structure,
 187                                                             const gchar             *fieldname,
 188                                                             GType                    type);
 189
 190 /* utility functions */
 191 gboolean                gst_structure_get_boolean          (const GstStructure      *structure,
 192                                                             const gchar             *fieldname,
 193                                                             gboolean                *value);
 194 gboolean                gst_structure_get_int              (const GstStructure      *structure,
 195                                                             const gchar             *fieldname,
 196                                                             gint                    *value);
 197 gboolean                gst_structure_get_uint             (const GstStructure      *structure,
 198                                                             const gchar             *fieldname,
 199                                                             guint                   *value);
 200 gboolean                gst_structure_get_double           (const GstStructure      *structure,
 201                                                             const gchar             *fieldname,
 202                                                             gdouble                 *value);
 203 gboolean                gst_structure_get_date             (const GstStructure      *structure,
 204                                                             const gchar             *fieldname,
 205                                                             GDate                  **value);
 206 gboolean                gst_structure_get_date_time        (const GstStructure      *structure,
 207                                                             const gchar             *fieldname,
 208                                                             GstDateTime              **value);
 209 gboolean                gst_structure_get_clock_time       (const GstStructure      *structure,
 210                                                             const gchar             *fieldname,
 211                                                             GstClockTime            *value);
 212 const gchar *           gst_structure_get_string           (const GstStructure      *structure,
 213                                                             const gchar             *fieldname);
 214 gboolean                gst_structure_get_enum             (const GstStructure      *structure,
 215                                                             const gchar             *fieldname,
 216                                                             GType                    enumtype,
 217                                                             gint                    *value);
 218 gboolean                gst_structure_get_fraction         (const GstStructure      *structure,
 219                                                             const gchar             *fieldname,
 220                                                             gint *value_numerator,
 221                                                             gint *value_denominator);
 222
 223 gchar *                 gst_structure_to_string            (const GstStructure      *structure) G_GNUC_MALLOC;
 224 GstStructure *          gst_structure_from_string          (const gchar             *string,
 225                                                             gchar                  **end) G_GNUC_MALLOC;
 226
 227 gboolean                 gst_structure_fixate_field_nearest_int    (GstStructure *structure,
 228                                                                          const char   *field_name,
 229                                                                          int           target);
 230 gboolean                 gst_structure_fixate_field_nearest_double (GstStructure *structure,
 231                                                                          const char   *field_name,
 232                                                                          double        target);
 233
 234 gboolean                 gst_structure_fixate_field_boolean (GstStructure *structure,
 235                                                                          const char   *field_name,
 236                                                                          gboolean        target);
 237 gboolean                 gst_structure_fixate_field_string (GstStructure *structure,
 238                                                                          const char   *field_name,
 239                                                                          const gchar  *target);
 240 gboolean                 gst_structure_fixate_field_nearest_fraction (GstStructure *structure,
 241                                                                          const char   *field_name,
 242                                                                          const gint target_numerator,
 243                                                                          const gint target_denominator);
 244 gboolean                 gst_structure_fixate_field  (GstStructure *structure,
 245                                                       const char   *field_name);
 246
 247 gboolean                 gst_structure_is_equal(const GstStructure *structure1,
 248                                                 const GstStructure *structure2);
 249 gboolean                 gst_structure_is_subset(const GstStructure *subset,
 250                                                  const GstStructure *superset);
 251 gboolean                 gst_structure_can_intersect(const GstStructure *struct1,
 252                                                      const GstStructure *struct2);
 253 GstStructure*            gst_structure_intersect (const GstStructure *struct1,
 254                                                   const GstStructure *struct2)  G_GNUC_MALLOC;
 255 void                     gst_structure_fixate    (GstStructure *structure);
 256
 257 G_END_DECLS
 258
 259 #endif
 260