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_EXPORT GType _gst_structure_type;
33 typedef struct _GstStructure GstStructure;
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))
42 * GstStructureForeachFunc:
43 * @field_id: the #GQuark of the field name
44 * @value: the #GValue of the field
45 * @user_data: user data
47 * A function that will be called in gst_structure_foreach(). The function may
50 * Returns: %TRUE if the foreach operation should continue, %FALSE if
51 * the foreach operation should stop with %FALSE.
53 typedef gboolean (*GstStructureForeachFunc) (GQuark field_id,
58 * GstStructureMapFunc:
59 * @field_id: the #GQuark of the field name
60 * @value: the #GValue of the field
61 * @user_data: user data
63 * A function that will be called in gst_structure_map_in_place(). The function
66 * Returns: %TRUE if the map operation should continue, %FALSE if
67 * the map operation should stop with %FALSE.
69 typedef gboolean (*GstStructureMapFunc) (GQuark field_id,
74 * GstStructureFilterMapFunc:
75 * @field_id: the #GQuark of the field name
76 * @value: the #GValue of the field
77 * @user_data: user data
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.
83 * Returns: %TRUE if the field should be preserved, %FALSE if it
86 typedef gboolean (*GstStructureFilterMapFunc) (GQuark field_id,
92 * @type: the GType of a structure
94 * The GstStructure object. Most fields are private.
96 struct _GstStructure {
103 GType gst_structure_get_type (void);
105 GstStructure * gst_structure_new_empty (const gchar * name) G_GNUC_MALLOC;
107 GstStructure * gst_structure_new_id_empty (GQuark quark) G_GNUC_MALLOC;
109 GstStructure * gst_structure_new (const gchar * name,
110 const gchar * firstfield,
111 ...) G_GNUC_NULL_TERMINATED G_GNUC_MALLOC;
113 GstStructure * gst_structure_new_valist (const gchar * name,
114 const gchar * firstfield,
115 va_list varargs) G_GNUC_MALLOC;
117 GstStructure * gst_structure_new_id (GQuark name_quark,
121 GstStructure * gst_structure_new_from_string (const gchar * string);
123 GstStructure * gst_structure_copy (const GstStructure * structure) G_GNUC_MALLOC;
125 gboolean gst_structure_set_parent_refcount (GstStructure * structure,
128 void gst_structure_free (GstStructure * structure);
130 const gchar * gst_structure_get_name (const GstStructure * structure);
132 GQuark gst_structure_get_name_id (const GstStructure * structure);
134 gboolean gst_structure_has_name (const GstStructure * structure,
137 void gst_structure_set_name (GstStructure * structure,
140 void gst_structure_id_set_value (GstStructure * structure,
142 const GValue * value);
144 void gst_structure_set_value (GstStructure * structure,
145 const gchar * fieldname,
146 const GValue * value);
148 void gst_structure_id_take_value (GstStructure * structure,
152 void gst_structure_take_value (GstStructure * structure,
153 const gchar * fieldname,
156 void gst_structure_set (GstStructure * structure,
157 const gchar * fieldname,
158 ...) G_GNUC_NULL_TERMINATED;
160 void gst_structure_set_valist (GstStructure * structure,
161 const gchar * fieldname,
164 void gst_structure_id_set (GstStructure * structure,
166 ...) G_GNUC_NULL_TERMINATED;
168 void gst_structure_id_set_valist (GstStructure * structure,
172 gboolean gst_structure_get_valist (const GstStructure * structure,
173 const char * first_fieldname,
176 gboolean gst_structure_get (const GstStructure * structure,
177 const char * first_fieldname,
178 ...) G_GNUC_NULL_TERMINATED;
180 gboolean gst_structure_id_get_valist (const GstStructure * structure,
181 GQuark first_field_id,
184 gboolean gst_structure_id_get (const GstStructure * structure,
185 GQuark first_field_id,
186 ...) G_GNUC_NULL_TERMINATED;
188 const GValue * gst_structure_id_get_value (const GstStructure * structure,
191 const GValue * gst_structure_get_value (const GstStructure * structure,
192 const gchar * fieldname);
194 void gst_structure_remove_field (GstStructure * structure,
195 const gchar * fieldname);
197 void gst_structure_remove_fields (GstStructure * structure,
198 const gchar * fieldname,
199 ...) G_GNUC_NULL_TERMINATED;
201 void gst_structure_remove_fields_valist (GstStructure * structure,
202 const gchar * fieldname,
205 void gst_structure_remove_all_fields (GstStructure * structure);
207 GType gst_structure_get_field_type (const GstStructure * structure,
208 const gchar * fieldname);
210 gboolean gst_structure_foreach (const GstStructure * structure,
211 GstStructureForeachFunc func,
214 gboolean gst_structure_map_in_place (GstStructure * structure,
215 GstStructureMapFunc func,
218 void gst_structure_filter_and_map_in_place (GstStructure * structure,
219 GstStructureFilterMapFunc func,
222 gint gst_structure_n_fields (const GstStructure * structure);
224 const gchar * gst_structure_nth_field_name (const GstStructure * structure,
227 gboolean gst_structure_id_has_field (const GstStructure * structure,
230 gboolean gst_structure_id_has_field_typed (const GstStructure * structure,
234 gboolean gst_structure_has_field (const GstStructure * structure,
235 const gchar * fieldname);
237 gboolean gst_structure_has_field_typed (const GstStructure * structure,
238 const gchar * fieldname,
241 /* utility functions */
242 gboolean gst_structure_get_boolean (const GstStructure * structure,
243 const gchar * fieldname,
246 gboolean gst_structure_get_int (const GstStructure * structure,
247 const gchar * fieldname,
250 gboolean gst_structure_get_uint (const GstStructure * structure,
251 const gchar * fieldname,
254 gboolean gst_structure_get_int64 (const GstStructure * structure,
255 const gchar * fieldname,
258 gboolean gst_structure_get_uint64 (const GstStructure * structure,
259 const gchar * fieldname,
262 gboolean gst_structure_get_double (const GstStructure * structure,
263 const gchar * fieldname,
266 gboolean gst_structure_get_date (const GstStructure * structure,
267 const gchar * fieldname,
270 gboolean gst_structure_get_date_time (const GstStructure * structure,
271 const gchar * fieldname,
272 GstDateTime ** value);
274 gboolean gst_structure_get_clock_time (const GstStructure * structure,
275 const gchar * fieldname,
276 GstClockTime * value);
278 const gchar * gst_structure_get_string (const GstStructure * structure,
279 const gchar * fieldname);
281 gboolean gst_structure_get_enum (const GstStructure * structure,
282 const gchar * fieldname,
286 gboolean gst_structure_get_fraction (const GstStructure * structure,
287 const gchar * fieldname,
288 gint * value_numerator,
289 gint * value_denominator);
291 gboolean gst_structure_get_flagset (const GstStructure * structure,
292 const gchar * fieldname,
296 gchar * gst_structure_to_string (const GstStructure * structure) G_GNUC_MALLOC;
298 GstStructure * gst_structure_from_string (const gchar * string,
299 gchar ** end) G_GNUC_MALLOC;
301 gboolean gst_structure_fixate_field_nearest_int (GstStructure * structure,
302 const char * field_name,
305 gboolean gst_structure_fixate_field_nearest_double (GstStructure * structure,
306 const char * field_name,
309 gboolean gst_structure_fixate_field_boolean (GstStructure * structure,
310 const char * field_name,
313 gboolean gst_structure_fixate_field_string (GstStructure * structure,
314 const char * field_name,
315 const gchar * target);
317 gboolean gst_structure_fixate_field_nearest_fraction (GstStructure * structure,
318 const char * field_name,
319 const gint target_numerator,
320 const gint target_denominator);
322 gboolean gst_structure_fixate_field (GstStructure * structure,
323 const char * field_name);
325 void gst_structure_fixate (GstStructure * structure);
327 gboolean gst_structure_is_equal (const GstStructure * structure1,
328 const GstStructure * structure2);
330 gboolean gst_structure_is_subset (const GstStructure * subset,
331 const GstStructure * superset);
333 gboolean gst_structure_can_intersect (const GstStructure * struct1,
334 const GstStructure * struct2);
336 GstStructure * gst_structure_intersect (const GstStructure * struct1,
337 const GstStructure * struct2) G_GNUC_MALLOC;
339 #ifdef G_DEFINE_AUTOPTR_CLEANUP_FUNC
340 G_DEFINE_AUTOPTR_CLEANUP_FUNC(GstStructure, gst_structure_free)