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 extern 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 GstStructure * gst_structure_empty_new (const gchar * name);
87 GstStructure * gst_structure_id_empty_new (GQuark quark);
88 GstStructure * gst_structure_new (const gchar * name,
89 const gchar * firstfield,
91 GstStructure * gst_structure_new_valist (const gchar * name,
92 const gchar * firstfield,
94 GstStructure * gst_structure_id_new (GQuark name_quark,
97 GstStructure * gst_structure_copy (const GstStructure *structure);
98 gboolean gst_structure_set_parent_refcount (GstStructure *structure,
100 void gst_structure_free (GstStructure *structure);
102 G_CONST_RETURN gchar * gst_structure_get_name (const GstStructure *structure);
103 GQuark gst_structure_get_name_id (const GstStructure *structure);
104 gboolean gst_structure_has_name (const GstStructure *structure,
106 void gst_structure_set_name (GstStructure *structure,
109 gboolean gst_structure_is_equal (GstStructure *struct1,
110 GstStructure *struct2);
112 void gst_structure_id_set_value (GstStructure *structure,
114 const GValue *value);
115 void gst_structure_set_value (GstStructure *structure,
116 const gchar *fieldname,
117 const GValue *value);
118 void gst_structure_id_take_value (GstStructure *structure,
121 void gst_structure_take_value (GstStructure *structure,
122 const gchar *fieldname,
124 void gst_structure_set (GstStructure *structure,
125 const gchar *fieldname,
126 ...) G_GNUC_NULL_TERMINATED;
128 void gst_structure_set_valist (GstStructure *structure,
129 const gchar *fieldname,
132 void gst_structure_id_set (GstStructure *structure,
134 ...) G_GNUC_NULL_TERMINATED;
136 void gst_structure_id_set_valist (GstStructure *structure,
140 gboolean gst_structure_get_valist (const GstStructure *structure,
141 const char *first_fieldname,
144 gboolean gst_structure_get (const GstStructure *structure,
145 const char *first_fieldname,
146 ...) G_GNUC_NULL_TERMINATED;
148 gboolean gst_structure_id_get_valist (const GstStructure *structure,
149 GQuark first_field_id,
152 gboolean gst_structure_id_get (const GstStructure *structure,
153 GQuark first_field_id,
154 ...) G_GNUC_NULL_TERMINATED;
156 G_CONST_RETURN GValue * gst_structure_id_get_value (const GstStructure *structure,
158 G_CONST_RETURN GValue * gst_structure_get_value (const GstStructure *structure,
159 const gchar *fieldname);
160 void gst_structure_remove_field (GstStructure *structure,
161 const gchar *fieldname);
162 void gst_structure_remove_fields (GstStructure *structure,
163 const gchar *fieldname,
164 ...) G_GNUC_NULL_TERMINATED;
165 void gst_structure_remove_fields_valist (GstStructure *structure,
166 const gchar *fieldname,
168 void gst_structure_remove_all_fields (GstStructure *structure);
170 GType gst_structure_get_field_type (const GstStructure *structure,
171 const gchar *fieldname);
172 gboolean gst_structure_foreach (const GstStructure *structure,
173 GstStructureForeachFunc func,
175 gboolean gst_structure_map_in_place (GstStructure *structure,
176 GstStructureMapFunc func,
178 gint gst_structure_n_fields (const GstStructure *structure);
179 const gchar * gst_structure_nth_field_name (const GstStructure *structure, guint index);
180 gboolean gst_structure_id_has_field (const GstStructure *structure,
182 gboolean gst_structure_id_has_field_typed (const GstStructure *structure,
185 gboolean gst_structure_has_field (const GstStructure *structure,
186 const gchar *fieldname);
187 gboolean gst_structure_has_field_typed (const GstStructure *structure,
188 const gchar *fieldname,
191 /* utility functions */
192 gboolean gst_structure_get_boolean (const GstStructure *structure,
193 const gchar *fieldname,
195 gboolean gst_structure_get_int (const GstStructure *structure,
196 const gchar *fieldname,
198 gboolean gst_structure_get_uint (const GstStructure *structure,
199 const gchar *fieldname,
201 gboolean gst_structure_get_fourcc (const GstStructure *structure,
202 const gchar *fieldname,
204 gboolean gst_structure_get_double (const GstStructure *structure,
205 const gchar *fieldname,
207 gboolean gst_structure_get_date (const GstStructure *structure,
208 const gchar *fieldname,
210 gboolean gst_structure_get_date_time (const GstStructure *structure,
211 const gchar *fieldname,
212 GstDateTime **value);
213 gboolean gst_structure_get_clock_time (const GstStructure *structure,
214 const gchar *fieldname,
215 GstClockTime *value);
216 G_CONST_RETURN gchar * gst_structure_get_string (const GstStructure *structure,
217 const gchar *fieldname);
218 gboolean gst_structure_get_enum (const GstStructure *structure,
219 const gchar *fieldname,
222 gboolean gst_structure_get_fraction (const GstStructure *structure,
223 const gchar *fieldname,
224 gint *value_numerator,
225 gint *value_denominator);
227 gchar * gst_structure_to_string (const GstStructure *structure);
228 GstStructure * gst_structure_from_string (const gchar *string,
231 gboolean gst_structure_fixate_field_nearest_int (GstStructure *structure,
232 const char *field_name,
234 gboolean gst_structure_fixate_field_nearest_double (GstStructure *structure,
235 const char *field_name,
238 gboolean gst_structure_fixate_field_boolean (GstStructure *structure,
239 const char *field_name,
241 gboolean gst_structure_fixate_field_string (GstStructure *structure,
242 const char *field_name,
243 const gchar *target);
244 gboolean gst_structure_fixate_field_nearest_fraction (GstStructure *structure,
245 const char *field_name,
246 const gint target_numerator,
247 const gint target_denominator);