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_set_array (GstStructure * structure,
149 const gchar * fieldname,
150 const GValueArray * array);
152 void gst_structure_set_list (GstStructure * structure,
153 const gchar * fieldname,
154 const GValueArray * array);
156 void gst_structure_id_take_value (GstStructure * structure,
160 void gst_structure_take_value (GstStructure * structure,
161 const gchar * fieldname,
164 void gst_structure_set (GstStructure * structure,
165 const gchar * fieldname,
166 ...) G_GNUC_NULL_TERMINATED;
168 void gst_structure_set_valist (GstStructure * structure,
169 const gchar * fieldname,
172 void gst_structure_id_set (GstStructure * structure,
174 ...) G_GNUC_NULL_TERMINATED;
176 void gst_structure_id_set_valist (GstStructure * structure,
180 gboolean gst_structure_get_valist (const GstStructure * structure,
181 const char * first_fieldname,
184 gboolean gst_structure_get (const GstStructure * structure,
185 const char * first_fieldname,
186 ...) G_GNUC_NULL_TERMINATED;
188 gboolean gst_structure_id_get_valist (const GstStructure * structure,
189 GQuark first_field_id,
192 gboolean gst_structure_id_get (const GstStructure * structure,
193 GQuark first_field_id,
194 ...) G_GNUC_NULL_TERMINATED;
196 const GValue * gst_structure_id_get_value (const GstStructure * structure,
199 const GValue * gst_structure_get_value (const GstStructure * structure,
200 const gchar * fieldname);
202 void gst_structure_remove_field (GstStructure * structure,
203 const gchar * fieldname);
205 void gst_structure_remove_fields (GstStructure * structure,
206 const gchar * fieldname,
207 ...) G_GNUC_NULL_TERMINATED;
209 void gst_structure_remove_fields_valist (GstStructure * structure,
210 const gchar * fieldname,
213 void gst_structure_remove_all_fields (GstStructure * structure);
215 GType gst_structure_get_field_type (const GstStructure * structure,
216 const gchar * fieldname);
218 gboolean gst_structure_foreach (const GstStructure * structure,
219 GstStructureForeachFunc func,
222 gboolean gst_structure_map_in_place (GstStructure * structure,
223 GstStructureMapFunc func,
226 void gst_structure_filter_and_map_in_place (GstStructure * structure,
227 GstStructureFilterMapFunc func,
230 gint gst_structure_n_fields (const GstStructure * structure);
232 const gchar * gst_structure_nth_field_name (const GstStructure * structure,
235 gboolean gst_structure_id_has_field (const GstStructure * structure,
238 gboolean gst_structure_id_has_field_typed (const GstStructure * structure,
242 gboolean gst_structure_has_field (const GstStructure * structure,
243 const gchar * fieldname);
245 gboolean gst_structure_has_field_typed (const GstStructure * structure,
246 const gchar * fieldname,
249 /* utility functions */
250 gboolean gst_structure_get_boolean (const GstStructure * structure,
251 const gchar * fieldname,
254 gboolean gst_structure_get_int (const GstStructure * structure,
255 const gchar * fieldname,
258 gboolean gst_structure_get_uint (const GstStructure * structure,
259 const gchar * fieldname,
262 gboolean gst_structure_get_int64 (const GstStructure * structure,
263 const gchar * fieldname,
266 gboolean gst_structure_get_uint64 (const GstStructure * structure,
267 const gchar * fieldname,
270 gboolean gst_structure_get_double (const GstStructure * structure,
271 const gchar * fieldname,
274 gboolean gst_structure_get_date (const GstStructure * structure,
275 const gchar * fieldname,
278 gboolean gst_structure_get_date_time (const GstStructure * structure,
279 const gchar * fieldname,
280 GstDateTime ** value);
282 gboolean gst_structure_get_clock_time (const GstStructure * structure,
283 const gchar * fieldname,
284 GstClockTime * value);
286 const gchar * gst_structure_get_string (const GstStructure * structure,
287 const gchar * fieldname);
289 gboolean gst_structure_get_enum (const GstStructure * structure,
290 const gchar * fieldname,
294 gboolean gst_structure_get_fraction (const GstStructure * structure,
295 const gchar * fieldname,
296 gint * value_numerator,
297 gint * value_denominator);
299 gboolean gst_structure_get_flagset (const GstStructure * structure,
300 const gchar * fieldname,
304 gboolean gst_structure_get_array (GstStructure * structure,
305 const gchar * fieldname,
306 GValueArray ** array);
308 gboolean gst_structure_get_list (GstStructure * structure,
309 const gchar * fieldname,
310 GValueArray ** array);
312 gchar * gst_structure_to_string (const GstStructure * structure) G_GNUC_MALLOC;
314 GstStructure * gst_structure_from_string (const gchar * string,
315 gchar ** end) G_GNUC_MALLOC;
317 gboolean gst_structure_fixate_field_nearest_int (GstStructure * structure,
318 const char * field_name,
321 gboolean gst_structure_fixate_field_nearest_double (GstStructure * structure,
322 const char * field_name,
325 gboolean gst_structure_fixate_field_boolean (GstStructure * structure,
326 const char * field_name,
329 gboolean gst_structure_fixate_field_string (GstStructure * structure,
330 const char * field_name,
331 const gchar * target);
333 gboolean gst_structure_fixate_field_nearest_fraction (GstStructure * structure,
334 const char * field_name,
335 const gint target_numerator,
336 const gint target_denominator);
338 gboolean gst_structure_fixate_field (GstStructure * structure,
339 const char * field_name);
341 void gst_structure_fixate (GstStructure * structure);
343 gboolean gst_structure_is_equal (const GstStructure * structure1,
344 const GstStructure * structure2);
346 gboolean gst_structure_is_subset (const GstStructure * subset,
347 const GstStructure * superset);
349 gboolean gst_structure_can_intersect (const GstStructure * struct1,
350 const GstStructure * struct2);
352 GstStructure * gst_structure_intersect (const GstStructure * struct1,
353 const GstStructure * struct2) G_GNUC_MALLOC;
355 #ifdef G_DEFINE_AUTOPTR_CLEANUP_FUNC
356 G_DEFINE_AUTOPTR_CLEANUP_FUNC(GstStructure, gst_structure_free)