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 /** 36 * GstSerializeFlags: 37 * @GST_SERIALIZE_FLAG_NONE: No special flags specified. 38 * @GST_SERIALIZE_FLAG_BACKWARD_COMPAT: Serialize using the old format for 39 * nested structures. 40 * 41 * Since: 1.20 42 */ 43 typedef enum 44 { 45 GST_SERIALIZE_FLAG_NONE = 0, 46 GST_SERIALIZE_FLAG_BACKWARD_COMPAT = (1 << 0), 47 } GstSerializeFlags; 48 49 #define GST_TYPE_STRUCTURE (_gst_structure_type) 50 #define GST_IS_STRUCTURE(object) ((object) && (GST_STRUCTURE(object)->type == GST_TYPE_STRUCTURE)) 51 #define GST_STRUCTURE_CAST(object) ((GstStructure *)(object)) 52 #define GST_STRUCTURE(object) (GST_STRUCTURE_CAST(object)) 53 54 55 /** 56 * GstStructureForeachFunc: 57 * @field_id: the #GQuark of the field name 58 * @value: the #GValue of the field 59 * @user_data: user data 60 * 61 * A function that will be called in gst_structure_foreach(). The function may 62 * not modify @value. 63 * 64 * Returns: %TRUE if the foreach operation should continue, %FALSE if 65 * the foreach operation should stop with %FALSE. 66 */ 67 typedef gboolean (*GstStructureForeachFunc) (GQuark field_id, 68 const GValue * value, 69 gpointer user_data); 70 71 /** 72 * GstStructureMapFunc: 73 * @field_id: the #GQuark of the field name 74 * @value: the #GValue of the field 75 * @user_data: user data 76 * 77 * A function that will be called in gst_structure_map_in_place(). The function 78 * may modify @value. 79 * 80 * Returns: %TRUE if the map operation should continue, %FALSE if 81 * the map operation should stop with %FALSE. 82 */ 83 typedef gboolean (*GstStructureMapFunc) (GQuark field_id, 84 GValue * value, 85 gpointer user_data); 86 87 /** 88 * GstStructureFilterMapFunc: 89 * @field_id: the #GQuark of the field name 90 * @value: the #GValue of the field 91 * @user_data: user data 92 * 93 * A function that will be called in gst_structure_filter_and_map_in_place(). 94 * The function may modify @value, and the value will be removed from 95 * the structure if %FALSE is returned. 96 * 97 * Returns: %TRUE if the field should be preserved, %FALSE if it 98 * should be removed. 99 */ 100 typedef gboolean (*GstStructureFilterMapFunc) (GQuark field_id, 101 GValue * value, 102 gpointer user_data); 103 104 /** 105 * GstStructure: 106 * @type: the GType of a structure 107 * 108 * The GstStructure object. Most fields are private. 109 */ 110 struct _GstStructure { 111 GType type; 112 113 /*< private >*/ 114 GQuark name; 115 }; 116 117 GST_API 118 GType gst_structure_get_type (void); 119 120 GST_API 121 GstStructure * gst_structure_new_empty (const gchar * name) G_GNUC_MALLOC; 122 123 GST_API 124 GstStructure * gst_structure_new_id_empty (GQuark quark) G_GNUC_MALLOC; 125 126 GST_API 127 GstStructure * gst_structure_new (const gchar * name, 128 const gchar * firstfield, 129 ...) G_GNUC_NULL_TERMINATED G_GNUC_MALLOC; 130 GST_API 131 GstStructure * gst_structure_new_valist (const gchar * name, 132 const gchar * firstfield, 133 va_list varargs) G_GNUC_MALLOC; 134 GST_API 135 GstStructure * gst_structure_new_id (GQuark name_quark, 136 GQuark field_quark, 137 ...) G_GNUC_MALLOC; 138 GST_API 139 GstStructure * gst_structure_new_from_string (const gchar * string); 140 141 GST_API 142 GstStructure * gst_structure_copy (const GstStructure * structure) G_GNUC_MALLOC; 143 144 GST_API 145 gboolean gst_structure_set_parent_refcount (GstStructure * structure, 146 gint * refcount); 147 GST_API 148 void gst_structure_free (GstStructure * structure); 149 150 GST_API 151 void gst_clear_structure (GstStructure **structure_ptr); 152 #define gst_clear_structure(structure_ptr) g_clear_pointer ((structure_ptr), gst_structure_free) 153 154 GST_API 155 gboolean gst_structure_take (GstStructure ** oldstr_ptr, 156 GstStructure * newstr); 157 GST_API 158 const gchar * gst_structure_get_name (const GstStructure * structure); 159 160 GST_API 161 GQuark gst_structure_get_name_id (const GstStructure * structure); 162 163 GST_API 164 gboolean gst_structure_has_name (const GstStructure * structure, 165 const gchar * name); 166 GST_API 167 void gst_structure_set_name (GstStructure * structure, 168 const gchar * name); 169 GST_API 170 void gst_structure_id_set_value (GstStructure * structure, 171 GQuark field, 172 const GValue * value); 173 GST_API 174 void gst_structure_set_value (GstStructure * structure, 175 const gchar * fieldname, 176 const GValue * value); 177 GST_API 178 void gst_structure_set_array (GstStructure * structure, 179 const gchar * fieldname, 180 const GValueArray * array); 181 GST_API 182 void gst_structure_set_list (GstStructure * structure, 183 const gchar * fieldname, 184 const GValueArray * array); 185 GST_API 186 void gst_structure_id_take_value (GstStructure * structure, 187 GQuark field, 188 GValue * value); 189 GST_API 190 void gst_structure_take_value (GstStructure * structure, 191 const gchar * fieldname, 192 GValue * value); 193 GST_API 194 void gst_structure_set (GstStructure * structure, 195 const gchar * fieldname, 196 ...) G_GNUC_NULL_TERMINATED; 197 GST_API 198 void gst_structure_set_valist (GstStructure * structure, 199 const gchar * fieldname, 200 va_list varargs); 201 GST_API 202 void gst_structure_id_set (GstStructure * structure, 203 GQuark fieldname, 204 ...) G_GNUC_NULL_TERMINATED; 205 GST_API 206 void gst_structure_id_set_valist (GstStructure * structure, 207 GQuark fieldname, 208 va_list varargs); 209 GST_API 210 gboolean gst_structure_get_valist (const GstStructure * structure, 211 const char * first_fieldname, 212 va_list args); 213 GST_API 214 gboolean gst_structure_get (const GstStructure * structure, 215 const char * first_fieldname, 216 ...) G_GNUC_NULL_TERMINATED; 217 GST_API 218 gboolean gst_structure_id_get_valist (const GstStructure * structure, 219 GQuark first_field_id, 220 va_list args); 221 GST_API 222 gboolean gst_structure_id_get (const GstStructure * structure, 223 GQuark first_field_id, 224 ...) G_GNUC_NULL_TERMINATED; 225 GST_API 226 const GValue * gst_structure_id_get_value (const GstStructure * structure, 227 GQuark field); 228 GST_API 229 const GValue * gst_structure_get_value (const GstStructure * structure, 230 const gchar * fieldname); 231 GST_API 232 void gst_structure_remove_field (GstStructure * structure, 233 const gchar * fieldname); 234 GST_API 235 void gst_structure_remove_fields (GstStructure * structure, 236 const gchar * fieldname, 237 ...) G_GNUC_NULL_TERMINATED; 238 GST_API 239 void gst_structure_remove_fields_valist (GstStructure * structure, 240 const gchar * fieldname, 241 va_list varargs); 242 GST_API 243 void gst_structure_remove_all_fields (GstStructure * structure); 244 245 GST_API 246 GType gst_structure_get_field_type (const GstStructure * structure, 247 const gchar * fieldname); 248 GST_API 249 gboolean gst_structure_foreach (const GstStructure * structure, 250 GstStructureForeachFunc func, 251 gpointer user_data); 252 GST_API 253 gboolean gst_structure_map_in_place (GstStructure * structure, 254 GstStructureMapFunc func, 255 gpointer user_data); 256 GST_API 257 void gst_structure_filter_and_map_in_place (GstStructure * structure, 258 GstStructureFilterMapFunc func, 259 gpointer user_data); 260 GST_API 261 gint gst_structure_n_fields (const GstStructure * structure); 262 263 GST_API 264 const gchar * gst_structure_nth_field_name (const GstStructure * structure, 265 guint index); 266 GST_API 267 gboolean gst_structure_id_has_field (const GstStructure * structure, 268 GQuark field); 269 GST_API 270 gboolean gst_structure_id_has_field_typed (const GstStructure * structure, 271 GQuark field, 272 GType type); 273 GST_API 274 gboolean gst_structure_has_field (const GstStructure * structure, 275 const gchar * fieldname); 276 GST_API 277 gboolean gst_structure_has_field_typed (const GstStructure * structure, 278 const gchar * fieldname, 279 GType type); 280 281 /* utility functions */ 282 283 GST_API 284 gboolean gst_structure_get_boolean (const GstStructure * structure, 285 const gchar * fieldname, 286 gboolean * value); 287 GST_API 288 gboolean gst_structure_get_int (const GstStructure * structure, 289 const gchar * fieldname, 290 gint * value); 291 GST_API 292 gboolean gst_structure_get_uint (const GstStructure * structure, 293 const gchar * fieldname, 294 guint * value); 295 GST_API 296 gboolean gst_structure_get_int64 (const GstStructure * structure, 297 const gchar * fieldname, 298 gint64 * value); 299 GST_API 300 gboolean gst_structure_get_uint64 (const GstStructure * structure, 301 const gchar * fieldname, 302 guint64 * value); 303 GST_API 304 gboolean gst_structure_get_double (const GstStructure * structure, 305 const gchar * fieldname, 306 gdouble * value); 307 GST_API 308 gboolean gst_structure_get_date (const GstStructure * structure, 309 const gchar * fieldname, 310 GDate ** value); 311 GST_API 312 gboolean gst_structure_get_date_time (const GstStructure * structure, 313 const gchar * fieldname, 314 GstDateTime ** value); 315 GST_API 316 gboolean gst_structure_get_clock_time (const GstStructure * structure, 317 const gchar * fieldname, 318 GstClockTime * value); 319 GST_API 320 const gchar * gst_structure_get_string (const GstStructure * structure, 321 const gchar * fieldname); 322 GST_API 323 gboolean gst_structure_get_enum (const GstStructure * structure, 324 const gchar * fieldname, 325 GType enumtype, 326 gint * value); 327 GST_API 328 gboolean gst_structure_get_fraction (const GstStructure * structure, 329 const gchar * fieldname, 330 gint * value_numerator, 331 gint * value_denominator); 332 GST_API 333 gboolean gst_structure_get_flagset (const GstStructure * structure, 334 const gchar * fieldname, 335 guint * value_flags, 336 guint * value_mask); 337 GST_API 338 gboolean gst_structure_get_array (GstStructure * structure, 339 const gchar * fieldname, 340 GValueArray ** array); 341 GST_API 342 gboolean gst_structure_get_list (GstStructure * structure, 343 const gchar * fieldname, 344 GValueArray ** array); 345 GST_API 346 gchar * gst_structure_to_string (const GstStructure * structure) G_GNUC_MALLOC; 347 GST_API 348 gchar * gst_structure_serialize (const GstStructure * structure, 349 GstSerializeFlags flags) G_GNUC_MALLOC; 350 351 GST_API 352 GstStructure * gst_structure_from_string (const gchar * string, 353 gchar ** end) G_GNUC_MALLOC; 354 GST_API 355 gboolean gst_structure_fixate_field_nearest_int (GstStructure * structure, 356 const char * field_name, 357 int target); 358 GST_API 359 gboolean gst_structure_fixate_field_nearest_double (GstStructure * structure, 360 const char * field_name, 361 double target); 362 GST_API 363 gboolean gst_structure_fixate_field_boolean (GstStructure * structure, 364 const char * field_name, 365 gboolean target); 366 GST_API 367 gboolean gst_structure_fixate_field_string (GstStructure * structure, 368 const char * field_name, 369 const gchar * target); 370 GST_API 371 gboolean gst_structure_fixate_field_nearest_fraction (GstStructure * structure, 372 const char * field_name, 373 const gint target_numerator, 374 const gint target_denominator); 375 GST_API 376 gboolean gst_structure_fixate_field (GstStructure * structure, 377 const char * field_name); 378 GST_API 379 void gst_structure_fixate (GstStructure * structure); 380 381 GST_API 382 gboolean gst_structure_is_equal (const GstStructure * structure1, 383 const GstStructure * structure2); 384 GST_API 385 gboolean gst_structure_is_subset (const GstStructure * subset, 386 const GstStructure * superset); 387 GST_API 388 gboolean gst_structure_can_intersect (const GstStructure * struct1, 389 const GstStructure * struct2); 390 GST_API 391 GstStructure * gst_structure_intersect (const GstStructure * struct1, 392 const GstStructure * struct2) G_GNUC_MALLOC; 393 394 G_DEFINE_AUTOPTR_CLEANUP_FUNC(GstStructure, gst_structure_free) 395 396 G_END_DECLS 397 398 #endif 399 400