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., 59 Temple Place - Suite 330,
17 * Boston, MA 02111-1307, 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;
89 GstStructure * gst_structure_new_id_empty (GQuark quark) G_GNUC_MALLOC;
90 GstStructure * gst_structure_new (const gchar * name,
91 const gchar * firstfield,
92 ...) G_GNUC_NULL_TERMINATED G_GNUC_MALLOC;
93 GstStructure * gst_structure_new_valist (const gchar * name,
94 const gchar * firstfield,
95 va_list varargs) G_GNUC_MALLOC;
96 GstStructure * gst_structure_new_id (GQuark name_quark,
99 GstStructure * gst_structure_copy (const GstStructure *structure) G_GNUC_MALLOC;
100 gboolean gst_structure_set_parent_refcount (GstStructure *structure,
102 void gst_structure_free (GstStructure *structure);
104 const gchar * gst_structure_get_name (const GstStructure *structure);
105 GQuark gst_structure_get_name_id (const GstStructure *structure);
106 gboolean gst_structure_has_name (const GstStructure *structure,
108 void gst_structure_set_name (GstStructure *structure,
111 void gst_structure_id_set_value (GstStructure *structure,
113 const GValue *value);
114 void gst_structure_set_value (GstStructure *structure,
115 const gchar *fieldname,
116 const GValue *value);
117 void gst_structure_id_take_value (GstStructure *structure,
120 void gst_structure_take_value (GstStructure *structure,
121 const gchar *fieldname,
123 void gst_structure_set (GstStructure *structure,
124 const gchar *fieldname,
125 ...) G_GNUC_NULL_TERMINATED;
127 void gst_structure_set_valist (GstStructure *structure,
128 const gchar *fieldname,
131 void gst_structure_id_set (GstStructure *structure,
133 ...) G_GNUC_NULL_TERMINATED;
135 void gst_structure_id_set_valist (GstStructure *structure,
139 gboolean gst_structure_get_valist (const GstStructure *structure,
140 const char *first_fieldname,
143 gboolean gst_structure_get (const GstStructure *structure,
144 const char *first_fieldname,
145 ...) G_GNUC_NULL_TERMINATED;
147 gboolean gst_structure_id_get_valist (const GstStructure *structure,
148 GQuark first_field_id,
151 gboolean gst_structure_id_get (const GstStructure *structure,
152 GQuark first_field_id,
153 ...) G_GNUC_NULL_TERMINATED;
155 const GValue * gst_structure_id_get_value (const GstStructure *structure,
157 const GValue * gst_structure_get_value (const GstStructure *structure,
158 const gchar *fieldname);
159 void gst_structure_remove_field (GstStructure *structure,
160 const gchar *fieldname);
161 void gst_structure_remove_fields (GstStructure *structure,
162 const gchar *fieldname,
163 ...) G_GNUC_NULL_TERMINATED;
164 void gst_structure_remove_fields_valist (GstStructure *structure,
165 const gchar *fieldname,
167 void gst_structure_remove_all_fields (GstStructure *structure);
169 GType gst_structure_get_field_type (const GstStructure *structure,
170 const gchar *fieldname);
171 gboolean gst_structure_foreach (const GstStructure *structure,
172 GstStructureForeachFunc func,
174 gboolean gst_structure_map_in_place (GstStructure *structure,
175 GstStructureMapFunc func,
177 gint gst_structure_n_fields (const GstStructure *structure);
178 const gchar * gst_structure_nth_field_name (const GstStructure *structure, guint index);
179 gboolean gst_structure_id_has_field (const GstStructure *structure,
181 gboolean gst_structure_id_has_field_typed (const GstStructure *structure,
184 gboolean gst_structure_has_field (const GstStructure *structure,
185 const gchar *fieldname);
186 gboolean gst_structure_has_field_typed (const GstStructure *structure,
187 const gchar *fieldname,
190 /* utility functions */
191 gboolean gst_structure_get_boolean (const GstStructure *structure,
192 const gchar *fieldname,
194 gboolean gst_structure_get_int (const GstStructure *structure,
195 const gchar *fieldname,
197 gboolean gst_structure_get_uint (const GstStructure *structure,
198 const gchar *fieldname,
200 gboolean gst_structure_get_double (const GstStructure *structure,
201 const gchar *fieldname,
203 gboolean gst_structure_get_date (const GstStructure *structure,
204 const gchar *fieldname,
206 gboolean gst_structure_get_date_time (const GstStructure *structure,
207 const gchar *fieldname,
208 GstDateTime **value);
209 gboolean gst_structure_get_clock_time (const GstStructure *structure,
210 const gchar *fieldname,
211 GstClockTime *value);
212 const gchar * gst_structure_get_string (const GstStructure *structure,
213 const gchar *fieldname);
214 gboolean gst_structure_get_enum (const GstStructure *structure,
215 const gchar *fieldname,
218 gboolean gst_structure_get_fraction (const GstStructure *structure,
219 const gchar *fieldname,
220 gint *value_numerator,
221 gint *value_denominator);
223 gchar * gst_structure_to_string (const GstStructure *structure) G_GNUC_MALLOC;
224 GstStructure * gst_structure_from_string (const gchar *string,
225 gchar **end) G_GNUC_MALLOC;
227 gboolean gst_structure_fixate_field_nearest_int (GstStructure *structure,
228 const char *field_name,
230 gboolean gst_structure_fixate_field_nearest_double (GstStructure *structure,
231 const char *field_name,
234 gboolean gst_structure_fixate_field_boolean (GstStructure *structure,
235 const char *field_name,
237 gboolean gst_structure_fixate_field_string (GstStructure *structure,
238 const char *field_name,
239 const gchar *target);
240 gboolean gst_structure_fixate_field_nearest_fraction (GstStructure *structure,
241 const char *field_name,
242 const gint target_numerator,
243 const gint target_denominator);
244 gboolean gst_structure_fixate_field (GstStructure *structure,
245 const char *field_name);
247 gboolean gst_structure_is_equal(const GstStructure *structure1,
248 const GstStructure *structure2);
249 gboolean gst_structure_is_subset(const GstStructure *subset,
250 const GstStructure *superset);
251 gboolean gst_structure_can_intersect(const GstStructure *struct1,
252 const GstStructure *struct2);
253 GstStructure* gst_structure_intersect (const GstStructure *struct1,
254 const GstStructure *struct2) G_GNUC_MALLOC;
255 void gst_structure_fixate (GstStructure *structure);