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

source code of include/gstreamer-1.0/gst/gststructure.h