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 382