1/* GStreamer
2 * Copyright (C) 2003 David A. Schleef <ds@schleef.org>
3 *
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.
8 *
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.
13 *
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.
18 */
19
20#ifndef __GST_STRUCTURE_H__
21#define __GST_STRUCTURE_H__
22
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>
28
29G_BEGIN_DECLS
30
31GST_API GType _gst_structure_type;
32
33typedef struct _GstStructure GstStructure;
34
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))
39
40
41/**
42 * GstStructureForeachFunc:
43 * @field_id: the #GQuark of the field name
44 * @value: the #GValue of the field
45 * @user_data: user data
46 *
47 * A function that will be called in gst_structure_foreach(). The function may
48 * not modify @value.
49 *
50 * Returns: %TRUE if the foreach operation should continue, %FALSE if
51 * the foreach operation should stop with %FALSE.
52 */
53typedef gboolean (*GstStructureForeachFunc) (GQuark field_id,
54 const GValue * value,
55 gpointer user_data);
56
57/**
58 * GstStructureMapFunc:
59 * @field_id: the #GQuark of the field name
60 * @value: the #GValue of the field
61 * @user_data: user data
62 *
63 * A function that will be called in gst_structure_map_in_place(). The function
64 * may modify @value.
65 *
66 * Returns: %TRUE if the map operation should continue, %FALSE if
67 * the map operation should stop with %FALSE.
68 */
69typedef gboolean (*GstStructureMapFunc) (GQuark field_id,
70 GValue * value,
71 gpointer user_data);
72
73/**
74 * GstStructureFilterMapFunc:
75 * @field_id: the #GQuark of the field name
76 * @value: the #GValue of the field
77 * @user_data: user data
78 *
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.
82 *
83 * Returns: %TRUE if the field should be preserved, %FALSE if it
84 * should be removed.
85 */
86typedef gboolean (*GstStructureFilterMapFunc) (GQuark field_id,
87 GValue * value,
88 gpointer user_data);
89
90/**
91 * GstStructure:
92 * @type: the GType of a structure
93 *
94 * The GstStructure object. Most fields are private.
95 */
96struct _GstStructure {
97 GType type;
98
99 /*< private >*/
100 GQuark name;
101};
102
103GST_API
104GType gst_structure_get_type (void);
105
106GST_API
107GstStructure * gst_structure_new_empty (const gchar * name) G_GNUC_MALLOC;
108
109GST_API
110GstStructure * gst_structure_new_id_empty (GQuark quark) G_GNUC_MALLOC;
111
112GST_API
113GstStructure * gst_structure_new (const gchar * name,
114 const gchar * firstfield,
115 ...) G_GNUC_NULL_TERMINATED G_GNUC_MALLOC;
116GST_API
117GstStructure * gst_structure_new_valist (const gchar * name,
118 const gchar * firstfield,
119 va_list varargs) G_GNUC_MALLOC;
120GST_API
121GstStructure * gst_structure_new_id (GQuark name_quark,
122 GQuark field_quark,
123 ...) G_GNUC_MALLOC;
124GST_API
125GstStructure * gst_structure_new_from_string (const gchar * string);
126
127GST_API
128GstStructure * gst_structure_copy (const GstStructure * structure) G_GNUC_MALLOC;
129
130GST_API
131gboolean gst_structure_set_parent_refcount (GstStructure * structure,
132 gint * refcount);
133GST_API
134void gst_structure_free (GstStructure * structure);
135
136GST_API
137void gst_clear_structure (GstStructure **structure_ptr);
138#define gst_clear_structure(structure_ptr) g_clear_pointer ((structure_ptr), gst_structure_free)
139
140GST_API
141const gchar * gst_structure_get_name (const GstStructure * structure);
142
143GST_API
144GQuark gst_structure_get_name_id (const GstStructure * structure);
145
146GST_API
147gboolean gst_structure_has_name (const GstStructure * structure,
148 const gchar * name);
149GST_API
150void gst_structure_set_name (GstStructure * structure,
151 const gchar * name);
152GST_API
153void gst_structure_id_set_value (GstStructure * structure,
154 GQuark field,
155 const GValue * value);
156GST_API
157void gst_structure_set_value (GstStructure * structure,
158 const gchar * fieldname,
159 const GValue * value);
160GST_API
161void gst_structure_set_array (GstStructure * structure,
162 const gchar * fieldname,
163 const GValueArray * array);
164GST_API
165void gst_structure_set_list (GstStructure * structure,
166 const gchar * fieldname,
167 const GValueArray * array);
168GST_API
169void gst_structure_id_take_value (GstStructure * structure,
170 GQuark field,
171 GValue * value);
172GST_API
173void gst_structure_take_value (GstStructure * structure,
174 const gchar * fieldname,
175 GValue * value);
176GST_API
177void gst_structure_set (GstStructure * structure,
178 const gchar * fieldname,
179 ...) G_GNUC_NULL_TERMINATED;
180GST_API
181void gst_structure_set_valist (GstStructure * structure,
182 const gchar * fieldname,
183 va_list varargs);
184GST_API
185void gst_structure_id_set (GstStructure * structure,
186 GQuark fieldname,
187 ...) G_GNUC_NULL_TERMINATED;
188GST_API
189void gst_structure_id_set_valist (GstStructure * structure,
190 GQuark fieldname,
191 va_list varargs);
192GST_API
193gboolean gst_structure_get_valist (const GstStructure * structure,
194 const char * first_fieldname,
195 va_list args);
196GST_API
197gboolean gst_structure_get (const GstStructure * structure,
198 const char * first_fieldname,
199 ...) G_GNUC_NULL_TERMINATED;
200GST_API
201gboolean gst_structure_id_get_valist (const GstStructure * structure,
202 GQuark first_field_id,
203 va_list args);
204GST_API
205gboolean gst_structure_id_get (const GstStructure * structure,
206 GQuark first_field_id,
207 ...) G_GNUC_NULL_TERMINATED;
208GST_API
209const GValue * gst_structure_id_get_value (const GstStructure * structure,
210 GQuark field);
211GST_API
212const GValue * gst_structure_get_value (const GstStructure * structure,
213 const gchar * fieldname);
214GST_API
215void gst_structure_remove_field (GstStructure * structure,
216 const gchar * fieldname);
217GST_API
218void gst_structure_remove_fields (GstStructure * structure,
219 const gchar * fieldname,
220 ...) G_GNUC_NULL_TERMINATED;
221GST_API
222void gst_structure_remove_fields_valist (GstStructure * structure,
223 const gchar * fieldname,
224 va_list varargs);
225GST_API
226void gst_structure_remove_all_fields (GstStructure * structure);
227
228GST_API
229GType gst_structure_get_field_type (const GstStructure * structure,
230 const gchar * fieldname);
231GST_API
232gboolean gst_structure_foreach (const GstStructure * structure,
233 GstStructureForeachFunc func,
234 gpointer user_data);
235GST_API
236gboolean gst_structure_map_in_place (GstStructure * structure,
237 GstStructureMapFunc func,
238 gpointer user_data);
239GST_API
240void gst_structure_filter_and_map_in_place (GstStructure * structure,
241 GstStructureFilterMapFunc func,
242 gpointer user_data);
243GST_API
244gint gst_structure_n_fields (const GstStructure * structure);
245
246GST_API
247const gchar * gst_structure_nth_field_name (const GstStructure * structure,
248 guint index);
249GST_API
250gboolean gst_structure_id_has_field (const GstStructure * structure,
251 GQuark field);
252GST_API
253gboolean gst_structure_id_has_field_typed (const GstStructure * structure,
254 GQuark field,
255 GType type);
256GST_API
257gboolean gst_structure_has_field (const GstStructure * structure,
258 const gchar * fieldname);
259GST_API
260gboolean gst_structure_has_field_typed (const GstStructure * structure,
261 const gchar * fieldname,
262 GType type);
263
264/* utility functions */
265
266GST_API
267gboolean gst_structure_get_boolean (const GstStructure * structure,
268 const gchar * fieldname,
269 gboolean * value);
270GST_API
271gboolean gst_structure_get_int (const GstStructure * structure,
272 const gchar * fieldname,
273 gint * value);
274GST_API
275gboolean gst_structure_get_uint (const GstStructure * structure,
276 const gchar * fieldname,
277 guint * value);
278GST_API
279gboolean gst_structure_get_int64 (const GstStructure * structure,
280 const gchar * fieldname,
281 gint64 * value);
282GST_API
283gboolean gst_structure_get_uint64 (const GstStructure * structure,
284 const gchar * fieldname,
285 guint64 * value);
286GST_API
287gboolean gst_structure_get_double (const GstStructure * structure,
288 const gchar * fieldname,
289 gdouble * value);
290GST_API
291gboolean gst_structure_get_date (const GstStructure * structure,
292 const gchar * fieldname,
293 GDate ** value);
294GST_API
295gboolean gst_structure_get_date_time (const GstStructure * structure,
296 const gchar * fieldname,
297 GstDateTime ** value);
298GST_API
299gboolean gst_structure_get_clock_time (const GstStructure * structure,
300 const gchar * fieldname,
301 GstClockTime * value);
302GST_API
303const gchar * gst_structure_get_string (const GstStructure * structure,
304 const gchar * fieldname);
305GST_API
306gboolean gst_structure_get_enum (const GstStructure * structure,
307 const gchar * fieldname,
308 GType enumtype,
309 gint * value);
310GST_API
311gboolean gst_structure_get_fraction (const GstStructure * structure,
312 const gchar * fieldname,
313 gint * value_numerator,
314 gint * value_denominator);
315GST_API
316gboolean gst_structure_get_flagset (const GstStructure * structure,
317 const gchar * fieldname,
318 guint * value_flags,
319 guint * value_mask);
320GST_API
321gboolean gst_structure_get_array (GstStructure * structure,
322 const gchar * fieldname,
323 GValueArray ** array);
324GST_API
325gboolean gst_structure_get_list (GstStructure * structure,
326 const gchar * fieldname,
327 GValueArray ** array);
328GST_API
329gchar * gst_structure_to_string (const GstStructure * structure) G_GNUC_MALLOC;
330
331GST_API
332GstStructure * gst_structure_from_string (const gchar * string,
333 gchar ** end) G_GNUC_MALLOC;
334GST_API
335gboolean gst_structure_fixate_field_nearest_int (GstStructure * structure,
336 const char * field_name,
337 int target);
338GST_API
339gboolean gst_structure_fixate_field_nearest_double (GstStructure * structure,
340 const char * field_name,
341 double target);
342GST_API
343gboolean gst_structure_fixate_field_boolean (GstStructure * structure,
344 const char * field_name,
345 gboolean target);
346GST_API
347gboolean gst_structure_fixate_field_string (GstStructure * structure,
348 const char * field_name,
349 const gchar * target);
350GST_API
351gboolean gst_structure_fixate_field_nearest_fraction (GstStructure * structure,
352 const char * field_name,
353 const gint target_numerator,
354 const gint target_denominator);
355GST_API
356gboolean gst_structure_fixate_field (GstStructure * structure,
357 const char * field_name);
358GST_API
359void gst_structure_fixate (GstStructure * structure);
360
361GST_API
362gboolean gst_structure_is_equal (const GstStructure * structure1,
363 const GstStructure * structure2);
364GST_API
365gboolean gst_structure_is_subset (const GstStructure * subset,
366 const GstStructure * superset);
367GST_API
368gboolean gst_structure_can_intersect (const GstStructure * struct1,
369 const GstStructure * struct2);
370GST_API
371GstStructure * gst_structure_intersect (const GstStructure * struct1,
372 const GstStructure * struct2) G_GNUC_MALLOC;
373
374#ifdef G_DEFINE_AUTOPTR_CLEANUP_FUNC
375G_DEFINE_AUTOPTR_CLEANUP_FUNC(GstStructure, gst_structure_free)
376#endif
377
378G_END_DECLS
379
380#endif
381
382