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/glib-compat.h>
  27
  28 G_BEGIN_DECLS
  29
  30 #define GST_TYPE_STRUCTURE             (gst_structure_get_type ())
  31 #define GST_STRUCTURE(object)          ((GstStructure *)(object))
  32 #define GST_IS_STRUCTURE(object)       ((object) && (GST_STRUCTURE(object)->type == GST_TYPE_STRUCTURE))
  33
  34 typedef struct _GstStructure GstStructure;
  35
  36 /**
  37  * GstStructureForeachFunc:
  38  * @field_id: the #GQuark of the field name
  39  * @value: the #GValue of the field
  40  * @user_data: user data
  41  *
  42  * A function that will be called in gst_structure_foreach(). The function may
  43  * not modify @value.
  44  *
  45  * Returns: TRUE if the foreach operation should continue, FALSE if
  46  * the foreach operation should stop with FALSE.
  47  */
  48 typedef gboolean (*GstStructureForeachFunc) (GQuark   field_id,
  49                                              const GValue * value,
  50                                              gpointer user_data);
  51
  52 /**
  53  * GstStructureMapFunc:
  54  * @field_id: the #GQuark of the field name
  55  * @value: the #GValue of the field
  56  * @user_data: user data
  57  *
  58  * A function that will be called in gst_structure_map_in_place(). The function
  59  * may modify @value.
  60  *
  61  * Returns: TRUE if the map operation should continue, FALSE if
  62  * the map operation should stop with FALSE.
  63  */
  64 typedef gboolean (*GstStructureMapFunc)     (GQuark   field_id,
  65                                              GValue * value,
  66                                              gpointer user_data);
  67
  68 /**
  69  * GstStructure:
  70  * @type: the GType of a structure
  71  *
  72  * The GstStructure object. Most fields are private.
  73  */
  74 struct _GstStructure {
  75   GType type;
  76
  77   /*< private >*/
  78   GQuark name;
  79
  80   /* owned by parent structure, NULL if no parent */
  81   gint *parent_refcount;
  82
  83   GArray *fields;
  84
  85   gpointer _gst_reserved;
  86 };
  87
  88 GType                   gst_structure_get_type             (void);
  89
  90 GstStructure *          gst_structure_empty_new            (const gchar *            name);
  91 GstStructure *          gst_structure_id_empty_new         (GQuark                   quark);
  92 GstStructure *          gst_structure_new                  (const gchar *            name,
  93                                                             const gchar *            firstfield,
  94                                                             ...);
  95 GstStructure *          gst_structure_new_valist           (const gchar *            name,
  96                                                             const gchar *            firstfield,
  97                                                             va_list                  varargs);
  98 GstStructure *          gst_structure_copy                 (const GstStructure      *structure);
  99 void                    gst_structure_set_parent_refcount  (GstStructure            *structure,
 100                                                             gint            *refcount);
 101 void                    gst_structure_free                 (GstStructure            *structure);
 102
 103 G_CONST_RETURN gchar *  gst_structure_get_name             (const GstStructure      *structure);
 104 GQuark                  gst_structure_get_name_id          (const GstStructure      *structure);
 105 gboolean                gst_structure_has_name             (const GstStructure      *structure,
 106                                                             const gchar             *name);
 107 void                    gst_structure_set_name             (GstStructure            *structure,
 108                                                             const gchar             *name);
 109
 110 void                    gst_structure_id_set_value         (GstStructure            *structure,
 111                                                             GQuark                   field,
 112                                                             const GValue            *value);
 113 void                    gst_structure_set_value            (GstStructure            *structure,
 114                                                             const gchar             *fieldname,
 115                                                             const GValue            *value);
 116 void                    gst_structure_set                  (GstStructure            *structure,
 117                                                             const gchar             *fieldname,
 118                                                             ...) G_GNUC_NULL_TERMINATED;
 119
 120 void                    gst_structure_set_valist           (GstStructure            *structure,
 121                                                             const gchar             *fieldname,
 122                                                             va_list varargs);
 123
 124 void                    gst_structure_id_set                (GstStructure            *structure,
 125                                                             GQuark                   fieldname,
 126                                                             ...) G_GNUC_NULL_TERMINATED;
 127
 128 void                    gst_structure_id_set_valist         (GstStructure            *structure,
 129                                                             GQuark                   fieldname,
 130                                                             va_list varargs);
 131
 132
 133 G_CONST_RETURN GValue * gst_structure_id_get_value         (const GstStructure      *structure,
 134                                                             GQuark                   field);
 135 G_CONST_RETURN GValue * gst_structure_get_value            (const GstStructure      *structure,
 136                                                             const gchar             *fieldname);
 137 void                    gst_structure_remove_field         (GstStructure            *structure,
 138                                                             const gchar             *fieldname);
 139 void                    gst_structure_remove_fields        (GstStructure            *structure,
 140                                                              const gchar            *fieldname,
 141                                                             ...) G_GNUC_NULL_TERMINATED;
 142 void                    gst_structure_remove_fields_valist (GstStructure             *structure,
 143                                                             const gchar             *fieldname,
 144                                                             va_list                  varargs);
 145 void                    gst_structure_remove_all_fields    (GstStructure            *structure);
 146
 147 GType                   gst_structure_get_field_type       (const GstStructure      *structure,
 148                                                             const gchar             *fieldname);
 149 gboolean                gst_structure_foreach              (const GstStructure      *structure,
 150                                                             GstStructureForeachFunc  func,
 151                                                             gpointer                 user_data);
 152 gboolean                gst_structure_map_in_place         (GstStructure            *structure,
 153                                                             GstStructureMapFunc      func,
 154                                                             gpointer                 user_data);
 155 gint                    gst_structure_n_fields             (const GstStructure      *structure);
 156 const gchar *           gst_structure_nth_field_name       (const GstStructure      *structure, guint index);
 157 gboolean                gst_structure_has_field            (const GstStructure      *structure,
 158                                                             const gchar             *fieldname);
 159 gboolean                gst_structure_has_field_typed      (const GstStructure      *structure,
 160                                                             const gchar             *fieldname,
 161                                                             GType                    type);
 162
 163 /* utility functions */
 164 gboolean                gst_structure_get_boolean          (const GstStructure      *structure,
 165                                                             const gchar             *fieldname,
 166                                                             gboolean                *value);
 167 gboolean                gst_structure_get_int              (const GstStructure      *structure,
 168                                                             const gchar             *fieldname,
 169                                                             gint                    *value);
 170 gboolean                gst_structure_get_uint             (const GstStructure      *structure,
 171                                                             const gchar             *fieldname,
 172                                                             guint                   *value);
 173 gboolean                gst_structure_get_fourcc           (const GstStructure      *structure,
 174                                                             const gchar             *fieldname,
 175                                                             guint32                 *value);
 176 gboolean                gst_structure_get_double           (const GstStructure      *structure,
 177                                                             const gchar             *fieldname,
 178                                                             gdouble                 *value);
 179 gboolean                gst_structure_get_date             (const GstStructure      *structure,
 180                                                             const gchar             *fieldname,
 181                                                             GDate                  **value);
 182 gboolean                gst_structure_get_clock_time       (const GstStructure      *structure,
 183                                                             const gchar             *fieldname,
 184                                                             GstClockTime            *value);
 185 G_CONST_RETURN gchar *  gst_structure_get_string           (const GstStructure      *structure,
 186                                                             const gchar             *fieldname);
 187 gboolean                gst_structure_get_enum             (const GstStructure      *structure,
 188                                                             const gchar             *fieldname,
 189                                                             GType                    enumtype,
 190                                                             gint                    *value);
 191 gboolean                gst_structure_get_fraction         (const GstStructure      *structure,
 192                                                             const gchar             *fieldname,
 193                                                             gint *value_numerator,
 194                                                             gint *value_denominator);
 195
 196 gchar *                 gst_structure_to_string            (const GstStructure      *structure);
 197 GstStructure *          gst_structure_from_string          (const gchar             *string,
 198                                                             gchar                  **end);
 199
 200 gboolean                 gst_structure_fixate_field_nearest_int    (GstStructure *structure,
 201                                                                          const char   *field_name,
 202                                                                          int           target);
 203 gboolean                 gst_structure_fixate_field_nearest_double (GstStructure *structure,
 204                                                                          const char   *field_name,
 205                                                                          double        target);
 206
 207 gboolean                 gst_structure_fixate_field_boolean (GstStructure *structure,
 208                                                                          const char   *field_name,
 209                                                                          gboolean        target);
 210 gboolean                 gst_structure_fixate_field_nearest_fraction (GstStructure *structure,
 211                                                                          const char   *field_name,
 212                                                                          const gint target_numerator,
 213                                                                          const gint target_denominator);
 214
 215 G_END_DECLS
 216
 217 #endif
 218