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,
75 * @type: the GType of a structure
77 * The GstStructure object. Most fields are private.
79 struct _GstStructure {
86 GType gst_structure_get_type (void);
88 GstStructure * gst_structure_new_empty (const gchar * name) G_GNUC_MALLOC;
90 GstStructure * gst_structure_new_id_empty (GQuark quark) G_GNUC_MALLOC;
92 GstStructure * gst_structure_new (const gchar * name,
93 const gchar * firstfield,
94 ...) G_GNUC_NULL_TERMINATED G_GNUC_MALLOC;
96 GstStructure * gst_structure_new_valist (const gchar * name,
97 const gchar * firstfield,
98 va_list varargs) G_GNUC_MALLOC;
100 GstStructure * gst_structure_new_id (GQuark name_quark,
104 GstStructure * gst_structure_new_from_string (const gchar * string);
106 GstStructure * gst_structure_copy (const GstStructure * structure) G_GNUC_MALLOC;
108 gboolean gst_structure_set_parent_refcount (GstStructure * structure,
111 void gst_structure_free (GstStructure * structure);
113 const gchar * gst_structure_get_name (const GstStructure * structure);
115 GQuark gst_structure_get_name_id (const GstStructure * structure);
117 gboolean gst_structure_has_name (const GstStructure * structure,
120 void gst_structure_set_name (GstStructure * structure,
123 void gst_structure_id_set_value (GstStructure * structure,
125 const GValue * value);
127 void gst_structure_set_value (GstStructure * structure,
128 const gchar * fieldname,
129 const GValue * value);
131 void gst_structure_id_take_value (GstStructure * structure,
135 void gst_structure_take_value (GstStructure * structure,
136 const gchar * fieldname,
139 void gst_structure_set (GstStructure * structure,
140 const gchar * fieldname,
141 ...) G_GNUC_NULL_TERMINATED;
143 void gst_structure_set_valist (GstStructure * structure,
144 const gchar * fieldname,
147 void gst_structure_id_set (GstStructure * structure,
149 ...) G_GNUC_NULL_TERMINATED;
151 void gst_structure_id_set_valist (GstStructure * structure,
155 gboolean gst_structure_get_valist (const GstStructure * structure,
156 const char * first_fieldname,
159 gboolean gst_structure_get (const GstStructure * structure,
160 const char * first_fieldname,
161 ...) G_GNUC_NULL_TERMINATED;
163 gboolean gst_structure_id_get_valist (const GstStructure * structure,
164 GQuark first_field_id,
167 gboolean gst_structure_id_get (const GstStructure * structure,
168 GQuark first_field_id,
169 ...) G_GNUC_NULL_TERMINATED;
171 const GValue * gst_structure_id_get_value (const GstStructure * structure,
174 const GValue * gst_structure_get_value (const GstStructure * structure,
175 const gchar * fieldname);
177 void gst_structure_remove_field (GstStructure * structure,
178 const gchar * fieldname);
180 void gst_structure_remove_fields (GstStructure * structure,
181 const gchar * fieldname,
182 ...) G_GNUC_NULL_TERMINATED;
184 void gst_structure_remove_fields_valist (GstStructure * structure,
185 const gchar * fieldname,
188 void gst_structure_remove_all_fields (GstStructure * structure);
190 GType gst_structure_get_field_type (const GstStructure * structure,
191 const gchar * fieldname);
193 gboolean gst_structure_foreach (const GstStructure * structure,
194 GstStructureForeachFunc func,
197 gboolean gst_structure_map_in_place (GstStructure * structure,
198 GstStructureMapFunc func,
201 gint gst_structure_n_fields (const GstStructure * structure);
203 const gchar * gst_structure_nth_field_name (const GstStructure * structure,
206 gboolean gst_structure_id_has_field (const GstStructure * structure,
209 gboolean gst_structure_id_has_field_typed (const GstStructure * structure,
213 gboolean gst_structure_has_field (const GstStructure * structure,
214 const gchar * fieldname);
216 gboolean gst_structure_has_field_typed (const GstStructure * structure,
217 const gchar * fieldname,
220 /* utility functions */
221 gboolean gst_structure_get_boolean (const GstStructure * structure,
222 const gchar * fieldname,
225 gboolean gst_structure_get_int (const GstStructure * structure,
226 const gchar * fieldname,
229 gboolean gst_structure_get_uint (const GstStructure * structure,
230 const gchar * fieldname,
233 gboolean gst_structure_get_int64 (const GstStructure * structure,
234 const gchar * fieldname,
237 gboolean gst_structure_get_uint64 (const GstStructure * structure,
238 const gchar * fieldname,
241 gboolean gst_structure_get_double (const GstStructure * structure,
242 const gchar * fieldname,
245 gboolean gst_structure_get_date (const GstStructure * structure,
246 const gchar * fieldname,
249 gboolean gst_structure_get_date_time (const GstStructure * structure,
250 const gchar * fieldname,
251 GstDateTime ** value);
253 gboolean gst_structure_get_clock_time (const GstStructure * structure,
254 const gchar * fieldname,
255 GstClockTime * value);
257 const gchar * gst_structure_get_string (const GstStructure * structure,
258 const gchar * fieldname);
260 gboolean gst_structure_get_enum (const GstStructure * structure,
261 const gchar * fieldname,
265 gboolean gst_structure_get_fraction (const GstStructure * structure,
266 const gchar * fieldname,
267 gint * value_numerator,
268 gint * value_denominator);
270 gchar * gst_structure_to_string (const GstStructure * structure) G_GNUC_MALLOC;
272 GstStructure * gst_structure_from_string (const gchar * string,
273 gchar ** end) G_GNUC_MALLOC;
275 gboolean gst_structure_fixate_field_nearest_int (GstStructure * structure,
276 const char * field_name,
279 gboolean gst_structure_fixate_field_nearest_double (GstStructure * structure,
280 const char * field_name,
283 gboolean gst_structure_fixate_field_boolean (GstStructure * structure,
284 const char * field_name,
287 gboolean gst_structure_fixate_field_string (GstStructure * structure,
288 const char * field_name,
289 const gchar * target);
291 gboolean gst_structure_fixate_field_nearest_fraction (GstStructure * structure,
292 const char * field_name,
293 const gint target_numerator,
294 const gint target_denominator);
296 gboolean gst_structure_fixate_field (GstStructure * structure,
297 const char * field_name);
299 void gst_structure_fixate (GstStructure * structure);
301 gboolean gst_structure_is_equal (const GstStructure * structure1,
302 const GstStructure * structure2);
304 gboolean gst_structure_is_subset (const GstStructure * subset,
305 const GstStructure * superset);
307 gboolean gst_structure_can_intersect (const GstStructure * struct1,
308 const GstStructure * struct2);
310 GstStructure * gst_structure_intersect (const GstStructure * struct1,
311 const GstStructure * struct2) G_GNUC_MALLOC;