2 * Copyright (C) 2003 David A. Schleef <ds@schleef.org>
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.
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.
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.
20 #ifndef __GST_STRUCTURE_H__
21 #define __GST_STRUCTURE_H__
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>
31 GST_API GType _gst_structure_type;
33 typedef struct _GstStructure GstStructure;
37 * @GST_SERIALIZE_FLAG_NONE: No special flags specified.
38 * @GST_SERIALIZE_FLAG_BACKWARD_COMPAT: Serialize using the old format for
45 GST_SERIALIZE_FLAG_NONE = 0,
46 GST_SERIALIZE_FLAG_BACKWARD_COMPAT = (1 << 0),
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))
56 * GstStructureForeachFunc:
57 * @field_id: the #GQuark of the field name
58 * @value: the #GValue of the field
59 * @user_data: user data
61 * A function that will be called in gst_structure_foreach(). The function may
64 * Returns: %TRUE if the foreach operation should continue, %FALSE if
65 * the foreach operation should stop with %FALSE.
67 typedef gboolean (*GstStructureForeachFunc) (GQuark field_id,
72 * GstStructureMapFunc:
73 * @field_id: the #GQuark of the field name
74 * @value: the #GValue of the field
75 * @user_data: user data
77 * A function that will be called in gst_structure_map_in_place(). The function
80 * Returns: %TRUE if the map operation should continue, %FALSE if
81 * the map operation should stop with %FALSE.
83 typedef gboolean (*GstStructureMapFunc) (GQuark field_id,
88 * GstStructureFilterMapFunc:
89 * @field_id: the #GQuark of the field name
90 * @value: the #GValue of the field
91 * @user_data: user data
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.
97 * Returns: %TRUE if the field should be preserved, %FALSE if it
100 typedef gboolean (*GstStructureFilterMapFunc) (GQuark field_id,
106 * @type: the GType of a structure
108 * The GstStructure object. Most fields are private.
110 struct _GstStructure {
118 GType gst_structure_get_type (void);
121 GstStructure * gst_structure_new_empty (const gchar * name) G_GNUC_MALLOC;
124 GstStructure * gst_structure_new_id_empty (GQuark quark) G_GNUC_MALLOC;
127 GstStructure * gst_structure_new (const gchar * name,
128 const gchar * firstfield,
129 ...) G_GNUC_NULL_TERMINATED G_GNUC_MALLOC;
131 GstStructure * gst_structure_new_valist (const gchar * name,
132 const gchar * firstfield,
133 va_list varargs) G_GNUC_MALLOC;
135 GstStructure * gst_structure_new_id (GQuark name_quark,
139 GstStructure * gst_structure_new_from_string (const gchar * string);
142 GstStructure * gst_structure_copy (const GstStructure * structure) G_GNUC_MALLOC;
145 gboolean gst_structure_set_parent_refcount (GstStructure * structure,
148 void gst_structure_free (GstStructure * structure);
151 void gst_clear_structure (GstStructure **structure_ptr);
152 #define gst_clear_structure(structure_ptr) g_clear_pointer ((structure_ptr), gst_structure_free)
155 gboolean gst_structure_take (GstStructure ** oldstr_ptr,
156 GstStructure * newstr);
158 const gchar * gst_structure_get_name (const GstStructure * structure);
161 GQuark gst_structure_get_name_id (const GstStructure * structure);
164 gboolean gst_structure_has_name (const GstStructure * structure,
167 void gst_structure_set_name (GstStructure * structure,
170 void gst_structure_id_set_value (GstStructure * structure,
172 const GValue * value);
174 void gst_structure_set_value (GstStructure * structure,
175 const gchar * fieldname,
176 const GValue * value);
178 void gst_structure_set_array (GstStructure * structure,
179 const gchar * fieldname,
180 const GValueArray * array);
182 void gst_structure_set_list (GstStructure * structure,
183 const gchar * fieldname,
184 const GValueArray * array);
186 void gst_structure_id_take_value (GstStructure * structure,
190 void gst_structure_take_value (GstStructure * structure,
191 const gchar * fieldname,
194 void gst_structure_set (GstStructure * structure,
195 const gchar * fieldname,
196 ...) G_GNUC_NULL_TERMINATED;
198 void gst_structure_set_valist (GstStructure * structure,
199 const gchar * fieldname,
202 void gst_structure_id_set (GstStructure * structure,
204 ...) G_GNUC_NULL_TERMINATED;
206 void gst_structure_id_set_valist (GstStructure * structure,
210 gboolean gst_structure_get_valist (const GstStructure * structure,
211 const char * first_fieldname,
214 gboolean gst_structure_get (const GstStructure * structure,
215 const char * first_fieldname,
216 ...) G_GNUC_NULL_TERMINATED;
218 gboolean gst_structure_id_get_valist (const GstStructure * structure,
219 GQuark first_field_id,
222 gboolean gst_structure_id_get (const GstStructure * structure,
223 GQuark first_field_id,
224 ...) G_GNUC_NULL_TERMINATED;
226 const GValue * gst_structure_id_get_value (const GstStructure * structure,
229 const GValue * gst_structure_get_value (const GstStructure * structure,
230 const gchar * fieldname);
232 void gst_structure_remove_field (GstStructure * structure,
233 const gchar * fieldname);
235 void gst_structure_remove_fields (GstStructure * structure,
236 const gchar * fieldname,
237 ...) G_GNUC_NULL_TERMINATED;
239 void gst_structure_remove_fields_valist (GstStructure * structure,
240 const gchar * fieldname,
243 void gst_structure_remove_all_fields (GstStructure * structure);
246 GType gst_structure_get_field_type (const GstStructure * structure,
247 const gchar * fieldname);
249 gboolean gst_structure_foreach (const GstStructure * structure,
250 GstStructureForeachFunc func,
253 gboolean gst_structure_map_in_place (GstStructure * structure,
254 GstStructureMapFunc func,
257 void gst_structure_filter_and_map_in_place (GstStructure * structure,
258 GstStructureFilterMapFunc func,
261 gint gst_structure_n_fields (const GstStructure * structure);
264 const gchar * gst_structure_nth_field_name (const GstStructure * structure,
267 gboolean gst_structure_id_has_field (const GstStructure * structure,
270 gboolean gst_structure_id_has_field_typed (const GstStructure * structure,
274 gboolean gst_structure_has_field (const GstStructure * structure,
275 const gchar * fieldname);
277 gboolean gst_structure_has_field_typed (const GstStructure * structure,
278 const gchar * fieldname,
281 /* utility functions */
284 gboolean gst_structure_get_boolean (const GstStructure * structure,
285 const gchar * fieldname,
288 gboolean gst_structure_get_int (const GstStructure * structure,
289 const gchar * fieldname,
292 gboolean gst_structure_get_uint (const GstStructure * structure,
293 const gchar * fieldname,
296 gboolean gst_structure_get_int64 (const GstStructure * structure,
297 const gchar * fieldname,
300 gboolean gst_structure_get_uint64 (const GstStructure * structure,
301 const gchar * fieldname,
304 gboolean gst_structure_get_double (const GstStructure * structure,
305 const gchar * fieldname,
308 gboolean gst_structure_get_date (const GstStructure * structure,
309 const gchar * fieldname,
312 gboolean gst_structure_get_date_time (const GstStructure * structure,
313 const gchar * fieldname,
314 GstDateTime ** value);
316 gboolean gst_structure_get_clock_time (const GstStructure * structure,
317 const gchar * fieldname,
318 GstClockTime * value);
320 const gchar * gst_structure_get_string (const GstStructure * structure,
321 const gchar * fieldname);
323 gboolean gst_structure_get_enum (const GstStructure * structure,
324 const gchar * fieldname,
328 gboolean gst_structure_get_fraction (const GstStructure * structure,
329 const gchar * fieldname,
330 gint * value_numerator,
331 gint * value_denominator);
333 gboolean gst_structure_get_flagset (const GstStructure * structure,
334 const gchar * fieldname,
338 gboolean gst_structure_get_array (GstStructure * structure,
339 const gchar * fieldname,
340 GValueArray ** array);
342 gboolean gst_structure_get_list (GstStructure * structure,
343 const gchar * fieldname,
344 GValueArray ** array);
347 gboolean gst_structure_get_flags (const GstStructure * structure,
348 const gchar * fieldname,
353 gchar * gst_structure_to_string (const GstStructure * structure) G_GNUC_MALLOC;
355 gchar * gst_structure_serialize (const GstStructure * structure,
356 GstSerializeFlags flags) G_GNUC_MALLOC;
359 GstStructure * gst_structure_from_string (const gchar * string,
360 gchar ** end) G_GNUC_MALLOC;
362 gboolean gst_structure_fixate_field_nearest_int (GstStructure * structure,
363 const char * field_name,
366 gboolean gst_structure_fixate_field_nearest_double (GstStructure * structure,
367 const char * field_name,
370 gboolean gst_structure_fixate_field_boolean (GstStructure * structure,
371 const char * field_name,
374 gboolean gst_structure_fixate_field_string (GstStructure * structure,
375 const char * field_name,
376 const gchar * target);
378 gboolean gst_structure_fixate_field_nearest_fraction (GstStructure * structure,
379 const char * field_name,
380 const gint target_numerator,
381 const gint target_denominator);
383 gboolean gst_structure_fixate_field (GstStructure * structure,
384 const char * field_name);
386 void gst_structure_fixate (GstStructure * structure);
389 gboolean gst_structure_is_equal (const GstStructure * structure1,
390 const GstStructure * structure2);
392 gboolean gst_structure_is_subset (const GstStructure * subset,
393 const GstStructure * superset);
395 gboolean gst_structure_can_intersect (const GstStructure * struct1,
396 const GstStructure * struct2);
398 GstStructure * gst_structure_intersect (const GstStructure * struct1,
399 const GstStructure * struct2) G_GNUC_MALLOC;
401 G_DEFINE_AUTOPTR_CLEANUP_FUNC(GstStructure, gst_structure_free)